PDF 마크다운 목차 생성: 인쇄에 적합한 구조와 탐색 설계

목차는 단순한 장식이 아닙니다. 몇 페이지를 넘어서는 문서에서 목차는 독자가 원하는 절을 즉시 찾을 수 있는지, 아니면 PDF 전체를 헤매며 스크롤해야 하는지를 가르는 핵심 요소입니다.

md2pdf는 단일 문서용 목차를 자동 생성하고 여러 챕터로 구성된 도서용 목차도 구성합니다. 본 가이드에서는 목차 생성 원리와 명확한 헤딩 작성법, 목차를 비활성화하는 것이 좋은 상황을 안내합니다.

일반 변환 워크플로는 GitHub README를 PDF로 변환하는 방법을, 다중 파일 도서 제작은 다중 파일 마크다운 도서 제작을 참조하십시오.

목차(TOC) 기능의 실질적 구성 요소

단일 문서 미리보기에서 목차는 마크다운 본문 상단에 삽입되는 HTML 내비게이션 블록입니다. 문서 내 헤딩을 링크 목록으로 제공하여 브라우저 내 이동과 인쇄 엔진의 클릭 가능한 링크로 작동합니다.

이는 PDF 뷰어의 측면 북마크(책갈피)와는 다릅니다. 측면 책갈피는 브라우저 인쇄 엔진과 뷰어 환경에 따라 지원 여부가 달라집니다.

도서 제작 모드에서 목차는 선택된 챕터와 헤딩을 취합하여 정식 인쇄 페이지로 생성됩니다.

md2pdf가 목차를 생성하는 기준

단일 문서의 목차는 파싱된 마크다운을 기반으로 규칙에 따라 생성됩니다:

• 문서에 최소 3개 이상의 헤딩이 있어야 합니다.
• H1부터 H4까지의 헤딩이 포함됩니다.
• 중복된 헤딩 텍스트에도 고유한 앵커 ID가 부여됩니다.
• 화면의 스위치는 미리보기와 인쇄 출력 모두에 동일하게 적용됩니다.

# Project handbook

## Installation

### Requirements

## Configuration

### Environment variables

## Troubleshooting

표준적인 헤딩 구성 예시:

위 문서는 6개의 헤딩을 가지고 있으므로 문서 제목인 H1 아래 H2와 H3가 들여쓰기된 목차가 자동으로 생성됩니다.

목차 항목으로 자연스러운 헤딩 작성법

헤딩은 본문 내용을 요약하는 동시에 목차의 한 줄을 구성합니다. 문맥 없이 읽었을 때 모호한 제목은 피해야 합니다.

Vague:  ## Overview
Useful: ## Configure GitHub access
Vague:  ## Errors
Useful: ## Recover from a failed export

구체적인 명사와 동사를 사용하십시오:

구체적인 제목은 본문을 열어보지 않고도 찾고자 하는 정보의 유무를 알 수 있게 합니다. 한 줄을 넘지 않도록 간결하게 작성하십시오.

본문 주요 섹션은 H2부터 시작

문서 제목을 유일한 H1으로 두고 본문 섹션을 H2로 시작하는 규칙이 가장 이상적입니다:

1. 최상위 개념이 명확해집니다. H1은 문서 자체를 가리킵니다.
2. 하위 섹션이 자연스럽게 중첩됩니다. H3과 H4가 논리적으로 배치됩니다.
3. 인쇄 스타일이 단정해집니다. H1이 난립하여 문서가 파편화되는 현상을 막습니다.

파일마다 H1을 사용하는 기존 자료는 도서 제작 기능을 활용하는 것이 좋습니다.

중복 제목, 부록 및 긴 문서 다루기

앵커 ID가 중복되지 않더라도 목차에 동일한 제목이 반복되면 독자가 혼란을 겪습니다. 원본 소스에 맥락을 덧붙여 제목을 구분하십시오.

H4가 많은 대형 문서의 경우 목차가 지나치게 길어져 1페이지를 초과할 수 있습니다. 중요한 부분만 H2/H3로 승격시키고 세부 사항은 본문으로 내리십시오.

부록은 단순 번호 대신 ## 부록 A: 내보내기 한도처럼 명확한 명칭을 부여하십시오.

목차 포함 여부 결정 기준

매뉴얼, 기술 사양서, 가이드라인 등 참조 빈도가 높은 문서에는 목차가 필수적입니다. 반면 1~2페이지 분량의 짧은 공지나 메모에서는 목차를 끄는 편이 깔끔합니다.

생성된 PDF 내 목차 최종 확인

PDF를 열어 목차 링크가 올바른 위치로 이동하는지 확인하십시오. 코드 블록 서식은 PDF 마크다운 코드 블록 작성법을 참조하십시오.