目录绝非可有可无的装饰品。在超过数页的技术文档中，目录是决定读者能够直接定位到目标章节，还是必须在整个 PDF 中费力滚动的关键分水岭。
md2pdf 能够为单篇文档自动生成轻量级目录，并为多章节图书编译完整的总目录。这两项功能紧密关联但定位不同。本指南将阐明其生成机制、如何设计高可读性的标题体系，以及何时应当关闭目录。
转换完整流程请参阅如何将 GitHub README 转换为 PDF。若需整合多文件制书，请参阅构建多文件 Markdown 图书并导出 PDF。
目录功能的真实构成与表现形式
在单篇文档预览中，目录是置于正文顶部的 HTML 导航模块。它将文档内各级标题汇总为锚点链接。这些链接在浏览器预览中直接生效，并根据系统打印设置在生成的 PDF 中保持可点击状态。
它不同于 PDF 阅读器侧边栏的原生大纲书签。侧边栏书签的生成取决于各浏览器及虚拟打印机底层支持情况。
而在多文件图书制作模式下，总目录会被直接排版为独立的打印页面，涵盖所有已选章节与层级标题。
md2pdf 构建目录的判定规则
单篇文档的目录基于解析后的 Markdown 语法树自动化生成：
- 文档中必须至少包含 三个及以上标题。
- 自动提取 H1 至 H4 范围内的标题。
- 标题锚点经过去重算法处理，确保同名标题拥有独立锚点。
- 页面顶部的目录开关同时控制网页预览与最终打印输出。
# Project handbook
## Installation
### Requirements
## Configuration
### Environment variables
## Troubleshooting规范的标题大纲示例：
上述文档包含六个标题，因此系统会自动构建目录，以清晰的缩进展现层级关系。
编写适合充当目录条目的优质标题
好的标题承担双重使命：既要概括本节要旨，又要能脱离上下文在目录中独立成行并清晰表达含义。
Vague: ## Overview
Useful: ## Configure GitHub access
Vague: ## Errors
Useful: ## Recover from a failed export推荐使用具体的动词与专业名词：
右侧实用的标题能让读者无需翻页便对章节内容一目了然。避免标题过长导致换行折叠，也不要仅为了视觉加粗而滥用标题层级。
建议正文主章节统一起始于 H2
将文档名称作为唯一的 H1，正文主要章节均从 H2 开始，能带来三大核心优势：
- 目录层级界限分明。 H1 代表整篇文献，H2 构成核心篇章。
- 子章节嵌套自然。 H3 与 H4 顺理成章地隶属于所属大章节。
- 打印字阶协调稳定。 避免全文充斥多个同级 H1 导致版面割裂。
若已有文档习惯为每个小节使用独立 H1，建议使用多文件图书模式分别整合。
妥善处理同名标题、附录与长篇文档
虽然程序能通过数字后缀保证链接不冲突，但目录中出现完全相同的文字仍会让读者困惑。请在源文档中添加上下文限定词进行区分。
在结构复杂且包含大量 H4 的长文档中，若目录跨越多页，建议将重要小节提炼为 H2/H3，次要说明下沉至正文列表。
附录部分应采用如 ## 附录 A：系统导出限额说明 的完整描述，避免仅标注单薄的序号。
何时应当保留或关闭目录
对于操作手册、规范标准、技术白皮书等长篇参考文档，目录至关重要。而对于一至两页的简报、发版摘要或备忘录，关闭目录能使版面更加干练紧凑。
在最终 PDF 文件中检验目录效果
导出后请打开 PDF 实际验证：点击目录项确认跳转精准、翻页版面规整无重叠。若需优化表格排版，请查阅 Markdown 表格转 PDF 规范。
制作你自己的 README PDF
免费、无需登录，全程在浏览器本地完成。