다중 파일 마크다운 도서 제작 및 PDF 일괄 내보내기

단일 README는 훌륭한 첫인상을 주지만 완전한 매뉴얼을 담기에는 부족합니다. 설치, 설정, 운영, 문제 해결 문서로 분량이 늘어나면 긴 README는 스크롤하기도, 인쇄하기도 매우 힘든 문서가 됩니다.

md2pdf는 바로 이러한 문서 구조를 위해 ’도서 제작 워크플로’를 제공합니다. 공개 저장소 URL을 입력하고, 필요한 마크다운 파일을 선택해 순서를 정렬하고, 표지와 목차를 추가하여 하나의 완성된 도서로 인쇄하거나 챕터별 개별 PDF를 ZIP 파일로 다운로드할 수 있습니다. 모든 과정은 브라우저에서 실행되며 서버로 파일을 업로드하지 않습니다.

본 가이드에서는 도서 제작 기능의 원리와 저장소 정돈 팁을 설명합니다. 단일 문서만 필요하시다면 GitHub README를 PDF로 변환하는 방법을 먼저 확인하십시오.

단일 README 대신 도서 형태가 적합한 경우

문서가 자연스러운 챕터로 나뉘어 있고 독자가 챕터 간을 이동해야 할 때 도서 모드가 이상적입니다:

시작하기, 핵심 개념, API 레퍼런스가 분리된 제품 공식 문서.
주차별 강의 노트와 과제를 하나로 묶은 교육용 교재.
서비스 및 장애 유형별로 독립된 파일로 관리되는 운영 가이드(Runbook).
변경 기록, 업그레이드 안내, 마이그레이션 지침을 묶은 배포 문서.

분량이 매우 적거나 내용이 실시간으로 바뀌는 문서라면 단일 파일 방식이 더 적합합니다.

이 기능은 공개(Public) 저장소를 대상으로 합니다. 비공개 저장소는 브라우저 단에서 인증할 수 없으므로 지원되지 않습니다.

저장소 스캐너의 동작과 안전 한도

저장소 URL을 제공하면 도서 탐색기가 GitHub Git Trees API를 통해 트리를 읽고 검색 가능한 파일 트리를 구축합니다. 폴더 체크박스는 3단계 상태를 지원합니다.

브라우저 성능을 유지하기 위해 다음과 같은 명확한 한도가 적용됩니다:

1권당 최대 30개 파일.
파일당 최대 750 KB.
마크다운 총합 최대 6 MB.
파일 내용 수집 시 20초 타임아웃.
메인 탐색 시 최대 60회의 GitHub API 요청 예산.

docs/
├── 00-introduction.md
├── 01-installation.md
├── 02-configuration.md
├── 03-operations.md
└── 04-troubleshooting.md

권장되는 디렉터리 구성 예시:

숫자 접두사가 필수적인 것은 아니지만 저장소 내에서 읽기 순서를 명확히 드러내어 정렬 작업을 줄여줍니다.

챕터 선택 및 순서 정렬

트리에서 파일을 선택한 후 챕터 목록을 검토하십시오. 새로 선택한 파일은 맨 끝에 추가됩니다. 위로 이동, 아래로 이동, 삭제 버튼으로 순서를 조정하십시오.

실용적인 순서 정렬 수칙:

핵심 파일 위주로 선택. 30개 한도가 있지만 10~15개 내외의 챕터가 인쇄와 검토에 가장 좋습니다.
도입부를 맨 앞으로. 개요와 요구사항은 설치 안내보다 앞에 와야 합니다.
레퍼런스는 맨 뒤로. 부록이나 API 명세표는 후반부에 배치하십시오.
README 중복 방지. README를 포함할 경우 요약본인지 독립 챕터인지 역할을 명확히 하십시오.
생성된 임시 파일 제외. 의미 없는 로그 파일은 제외하십시오.

에디터에서 정한 순서 그대로 인쇄용 PDF와 ZIP 파일 내부 구조에 반영됩니다.

원본 마크다운 파일 준비

도서 렌더러는 선택한 각 파일을 독립된 챕터로 취급하며 파일명이나 경로를 바탕으로 챕터 헤딩을 추가합니다.

개별 챕터 파일의 시작 예시:

# Installation

This chapter assumes a supported Node.js version and a local clone.

모든 파일이 H1으로 시작하면 조립된 도서에서 명확한 챕터 구분이 형성됩니다.

추가 검토 사항:

상대 링크. 챕터 간의 링크는 선택된 파일 목록 내의 유효한 파일이어야 합니다.
이미지. 상대 경로 이미지는 가져오기 과정에서 GitHub 주소로 해결됩니다.
넓은 표. PDF 마크다운 표 변환을 참고하여 너비를 맞추십시오.
중복 제목. 목차 구분을 위해 챕터별 고유 명칭을 포함하십시오.

표지 및 목차 구성

도서 편집기에서 제목, 부제목, 표지 설명을 작성할 수 있습니다. 어떤 문서인지, 대상 독자가 누구인지, 어떤 버전인지 명시하십시오.

목차는 선택된 챕터와 헤딩으로부터 자동 생성됩니다. 표지나 목차 설정을 변경하면 재조립 필요 상태로 표시되어 불일치를 방지합니다.

도서 인쇄 및 ZIP 일괄 내보내기

두 가지 출력 방식 중 선택할 수 있습니다:

전체 도서 인쇄. 표지, 목차, 전 챕터를 결합하여 브라우저 인쇄 창으로 전송합니다.
ZIP 내보내기. 선택된 각 챕터를 개별 PDF로 렌더링하여 하나의 ZIP 압축 파일로 일괄 다운로드합니다.

ZIP 파일명은 md2pdf-{owner}-{repo}-{sha8}.zip 형태이며 한글 및 유니코드 파일명이 안전하게 정규화됩니다.

한도 초과, 장애 대응 및 복구

GitHub API 호출 한도에 도달했다면 재설정 시간을 기다리거나 특정 폴더 URL을 직접 입력하십시오. 이미지를 불러오지 못하더라도 대체 표시로 전환되어 문서 조립은 안전하게 완료됩니다.

시각적 테마 차이는 인쇄 테마 비교 가이드를 참고하십시오.

나만의 README PDF 만들기

무료이고 로그인이 필요 없으며, 모든 처리가 클라이언트에서 이루어집니다.

변환기 열기