마크다운 문서를 개별 PDF로 변환하여 단일 ZIP 압축 파일로 일괄 내보내기

모든 문서를 한 권의 책으로 합치는 것도 훌륭한 방법이지만, 업무 환경에 따라서는 각 기능 가이드나 규정집을 독립된 개별 PDF 문서로 나누어 보관해야 할 때가 많습니다. 수십 개의 문서를 하나씩 내려받으면 브라우저 다운로드 팝업이 반복되고 다운로드 폴더가 지저분해집니다. md2pdf를 사용하면 여러 마크다운 파일을 개별 PDF로 일괄 변환한 후 단일 ZIP 파일로 압축하여 손쉽게 내려받을 수 있습니다.

이 튜토리얼에서는 일괄 PDF 생성 원리, JSZip을 활용한 브라우저 내부 ZIP 압축 방식, 효율적인 모듈형 내보내기 구조를 다룹니다.

통합 서적 대신 개별 PDF를 선택해야 하는 경우

문서의 배포 방식과 목적에 따라 최적의 출력 방식을 선택할 수 있습니다:

• 모듈별 선별 배포: 전체 저장소 문서를 전부 전달할 필요 없이 고객이나 협력사에 필요한 특정 안내서만 분리하여 공유할 때 유용합니다.
• 마이크로 문서 관리: 개별 API 엔드포인트 명세서나 배포 릴리스 노트를 토픽별 독립 파일로 체계적으로 아카이빙할 수 있습니다.
• 브라우저 다운로드 차단 방지: 모든 문서를 하나의 ZIP 파일로 묶어 제공하므로 브라우저의 다중 파일 다운로드 차단 경고를 원천적으로 방지합니다.

Export Modes in md2pdf:
Mode A (Consolidated Book):
- Multi-chapter single PDF (e.g., project-documentation.pdf)
- Unified Table of Contents & continuous page numbering

Mode B (ZIP Archive Bundle):
- project-docs-bundle.zip
  ├── 01-getting-started.pdf
  ├── 02-architecture.pdf
  └── 03-api-reference.pdf

JSZip 기반의 클라이언트 사이드 압축 처리

md2pdf는 검증된 JSZip 라이브러리를 통해 외부 서버 통신 없이 사용자 브라우저 내부에서 직접 압축 파일을 생성합니다:

1. 순차 렌더링: 선택된 각 마크다운 문서는 pdf-lib 엔진을 통해 독립적인 PDF 바이너리 버퍼로 렌더링됩니다.
2. 명확한 파일명 부여: 원본 마크다운 파일명이나 문서의 대표 제목을 바탕으로 가독성 높은 PDF 파일명이 자동으로 지정됩니다.
3. 인메모리 압축: 렌더링이 완료된 PDF 데이터는 메모리상에서 즉시 ZIP 파일 스트림으로 압축되어 추가됩니다.
4. 원클릭 일괄 다운로드: 모든 문서 처리가 끝나면 완벽하게 패키징된 ZIP 파일이 단 한 번의 다운로드 명령으로 사용자에게 전달됩니다.

ZIP 내부 폴더 디렉터리 계층 보존

다단계 디렉터리를 가진 저장소 문서를 내보낼 때 md2pdf는 폴더 구조 보존 여부를 유연하게 지원합니다:

• 디렉터리 구조 유지: docs/api/endpoints.md 파일은 ZIP 압축 파일 안에서도 docs/api/endpoints.pdf 경로에 정돈되어 저장됩니다.
• 단일 폴더 평탄화: 하위 폴더 없이 모든 PDF를 루트 경로에 모으고 이름 충돌을 방지하는 평탄화 모드도 지원합니다.

브라우저 메모리 관리 및 성능 최적화

수십 개의 고품질 PDF를 연속해서 렌더링할 때 브라우저 메모리가 과도하게 소모되지 않도록 제어하는 것이 중요합니다.

md2pdf는 변환 작업을 순차적으로 분할 실행하며 각 문서 렌더링이 끝날 때마다 중간 DOM 노드와 이미지 버퍼를 즉각 메모리에서 해제합니다. 가비지 컬렉션에 친화적인 구조 덕분에 수백 페이지 분량의 문서를 처리하더라도 탭 꺼짐 없이 안정적으로 동작합니다.

md2pdf에서 ZIP 패키지 내보내기

ZIP 번들을 생성하려면 파일 목록에서 변환할 마크다운 문서들을 선택하고, 출력 모드를 ’개별 PDF (ZIP)’로 설정한 뒤 내보내기 버튼을 클릭합니다. 몇 초 만에 모든 가이드가 깔끔하게 정리된 압축 파일로 다운로드됩니다.