单份 README 是绝佳的项目门面，但它无法承载完整详尽的系统手册。随着文档扩展至安装、配置、日常运维和故障排查等众多板块，极其冗长的单页 README 会演变成难以通读、更难以手动分页打印的噩梦。
md2pdf 专门为这种规模的技术文献研发了“多文件图书工作流”。只需输入公开仓库地址，在文件树中勾选所需 Markdown 章节并调整阅读次序，系统便会自动生成统一封面与全书目录。您可以直接打印整部图书，或一键打包下载包含各章节独立 PDF 的 ZIP 压缩包。全部环节均在浏览器本地安全运转，绝不将源文档上传至云端服务器。
本指南将详述图书工作流的运作逻辑与仓库文件组织准则。若您仅需转换单份文档，请先查阅如何将 GitHub README 转换为 PDF。
何时应当选择多文件图书而非单页 README
当文档自然具备多个独立章节，且读者需要在篇章之间快速定位查阅时，图书模式最为理想：
- 包含环境搭建、核心架构与 API 参考的产品官方技术文档。
- 整合了按教学周划分的教案、笔记与作业的课程讲义手册。
- 针对每项微服务或应急流程分别立卷的运维操作规程（Runbook）。
- 融合了发版说明、升级指南与历史归档的版本发布全集。
对于短小精悍或随时频繁变更的文档，单篇转换模式更为轻巧敏捷。
图书工作流要求源目标必须为 公开（Public）代码仓库。由于浏览器无法替您代持私有密钥，目前不支持私有仓库。
仓库扫描器的执行逻辑与防护配额
输入仓库地址后，图书资源管理器将调用 GitHub Git Trees API 遍历目录树，构建支持三态复选框的检索文件树。
为确保浏览器运行流畅，扫描器设置了明确的安全上限：
- 每本图书最多支持 30 个文件。
- 单个文件体积上限为 750 KB。
- 全书 Markdown 文本总容量上限为 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 章的规模最便于审阅与翻阅。
- 导言开门见山。 架构概念与前置要求应置于安装指南之前。
- 附录置于卷末。 术语表、命令速查表和错误码对照表置于文末最为合理。
- 厘清 README 定位。 若将 README 作为独立章节，需明确其究竟属于全书概览还是摘要总结。
- 剔除冗余构建产物。 排除无序的自动生成日志。
编辑器中确定的排列顺序，将严格映射至生成的打印 PDF 篇章及 ZIP 压缩包内部的目录层级中。
规范准备源 Markdown 文档
排版引擎将每个选中的 Markdown 文件视为独立的章，并以文件名或路径作为章标题进行分页隔离渲染。
章节文件的规范开头示例：
# Installation
This chapter assumes a supported Node.js version and a local clone.如果每个源文件均起始于 H1 标题，组装后的图书将拥有极其鲜明的篇章界限。
排查注意要点：
- 跨文件相对链接。 章节之间的超链接应当指向图书已包含的有效文档。
- 图片资源路径。 相对路径图片将在抓取时由程序自动解析为 GitHub 远端路径。
- 超宽数据表格。 请参考 Markdown 表格转 PDF 规范 提前收敛列宽。
- 规避重复标题。 避免不同章节出现一模一样的 H2 标题，以免导致全书总目录产生混淆。
设计全书封面与总目录
在图书设置中可自定义图书主标题、副标题及封面说明。开宗明义地告诉读者这是什么系统、面向哪类受众以及所属版本。
全书总目录由已选章节的各级标题动态编译生成。若修改封面元数据或重排章节，系统会自动将当前图书状态标记为“待更新”，杜绝打印出内容脱节的残缺成品。
全书一体化打印与 ZIP 批量导出
系统提供两种专业的导出途径：
- 全书一体化打印。 将带有封面、总目录与全部章节的完整排版整体交付至浏览器打印对话框，直接保存为完整电子书。
- ZIP 压缩包打包。 由 pdf-lib 为每个独立章节单独渲染生成一份精美的 A4 PDF，并打包成 ZIP 压缩包直接下载。
导出的 ZIP 包统一命名为 md2pdf-{owner}-{repo}-{sha8}.zip，文件名经过 NFC 规范化处理，完美兼容中文等多语言字符。
配额上限、网络异常与应急恢复
若因 GitHub API 访问频率超限报错，可稍等重置周期，或直接输入具体子目录的精确 URL 进行定向缩小抓取。个别外链图片加载失败时会自动降级为占位提示，绝不影响全书核心文字的完整导出。
更多主题排版细节，请参阅 Clean、Business、Academic 与 Dark 主题解析。
制作你自己的 README PDF
免费、无需登录，全程在浏览器本地完成。