将 README 转为 PDF 的 7 个实用场景

如果对方本来就常驻 GitHub，仓库链接是分享文档的好方法；但对其他所有人来说，它都很糟糕。审阅者会丢失上下文，客户不想注册账号，而 URL 也不是归档。PDF 能解决分发问题，但前提是它被有意识地制作出来。

md2pdf 围绕一条克制的流程构建：从公开仓库、本地文件或剪贴板获取 Markdown；以 GitHub 风格 Markdown 渲染；应用打印样式表；送入浏览器的“另存为 PDF”对话框。这种克制很有用。它意味着同一个工具既能服务五页的客户交付，也能服务五十页的课程读本，而无需服务器、账号或上传。

下面介绍七个能体现这套流程价值的场景，并说明让每个场景奏效的设置与准备工作。

1. 客户与相关方交付

客户很少会为了读一份项目概览而要求仓库访问权限。他们想要的是一份能打开、能转发给同事、能在会议上批注的文档。README PDF 往往正好提供恰当的细节层级：范围、架构说明、安装步骤、截图和已知限制，全都放在一个文件里。

推荐设置：

• 主题：对外受众用商务，技术背景很深的客户用简洁。
• 目录：超过四页的文档开启。
• 页面尺寸：匹配客户所在地区——欧洲和亚洲大部分地区用 A4，美国和加拿大用 Letter。
• 来源：仓库公开时直接获取；否则粘贴 Markdown 或上传 README 文件。

重要的准备工作：

• 导出前移除内部工单链接、预发布环境 URL 和凭据。工具不会上传文档，但 PDF 仍然是可以被转发的文件。
• 把相对图片路径替换为确实存在的仓库路径。md2pdf 会在获取仓库时解析它们，但源图片损坏，PDF 中依然会损坏。
• 检查 README 是否以摘要开篇，而不是更新日志。交付文档应当先告诉读者项目是什么，再告诉他们改了什么。
• 如果 README 把安装说明与架构背景混在一起，请添加一段简短的“如何阅读本文档”。

如果客户会在评审中引用具体页码，请使用浏览器的页码选项。应用的打印样式表本身不会添加页码；浏览器页眉和页脚是最简单的实现方式。

2. 离线归档与版本文档

只存在于仓库中的文档，会在读者脚下不断变化。当你需要记录某个版本在某一时点的样貌时，PDF 是稳定的产物。它可以与二进制文件放在一起、附加到发布记录，或存入项目档案，而不必担心未来的 README 改写。

推荐设置：

• 主题：简洁。
• 目录：开启。
• 文件名：包含仓库、发布标签或提交，以及日期，例如 acme-api-v2.4.0-readme-2026-10-02.pdf。
• 来源：获取公开仓库，然后确认你导出的正是想要的 README。应用读取默认分支，因此如果需要锁定标签或提交，请使用粘贴方式。

重要的准备工作：

• 在文档或文件名中记录来源。没有版本信息的 PDF，不过是又一份没有日期的附件。
• 归档前检查链接。blob 链接会始终指向仓库的默认分支。如果你需要标签或提交的真正快照，请粘贴该版本的 README，而不是使用获取流程，并在页脚行或随附的发布记录中注明提交哈希。
• 如果浏览器页眉和页脚包含本地文件路径或内部主机名，请将其禁用。归档应当自包含，而不是泄露生成它的机器信息。
• 如果归档需要可复现，请把 Markdown 源文件与 PDF 一并保存。PDF 是产物，Markdown 是配方。

这也是审阅阶段使用深色主题的好场景：在屏幕上阅读预览，然后导出，并清楚打印样式表会为纸张将其调亮。只需检查最终 PDF，而不要假设屏幕上的样子就是打印机将收到的样子。

3. 学术提交与课程包

学生和教师常常有 Markdown 笔记、项目文档或阅读材料，需要作为单一文档提交或分发。学术主题与产品 README 的任务不同：它需要充裕的论述空间、克制的代码块，以及一种不像落地页的版式。

推荐设置：

• 主题：学术。
• 目录：超过三个章节的文档开启。
• 页面尺寸：遵循院校要求。美国以外常用 A4，美国常用 Letter。
• 来源：如果作品未公开，请上传或粘贴 Markdown。绝不要为了转换而把未发表的作品放进公开仓库。

重要的准备工作：

• 导出前检查标题层级。标题跳级的课程读本会生成令人困惑的目录。
• 学术主题会对正文做两端对齐。很长的 URL、代码标识符和公式可能产生尴尬的间距。请把长 URL 改为引用式链接，或移入类似脚注的章节。
• 保持代码块简短。该主题使用打印效果良好的浅色代码背景，但 120 个字符的行仍会溢出页面。
• 如果文档包含引文，请把它们作为参考文献章节保留在 Markdown 中。md2pdf 只渲染文本，不管理引文格式。
• 提交前打印一份草稿。两端对齐的文本和衬线字体在纸上的观感可能与预览不同。

由于转换在客户端完成，未发表的笔记和论文草稿不会离开浏览器。相比于“把你的文档粘贴到我们的转换器”这类服务，这是实实在在的优势。

4. 内部评审材料与发布说明

工程团队常常需要一份单一文档，用于设计评审、发布就绪检查或事故后的跟进。来源可能已经是 README 或文档页面。把它转成 PDF，可以为会议建立固定议程，并留下审阅者所见内容的记录。

推荐设置：

• 主题：工程评审用简洁，跨职能受众用商务。
• 目录：开启。
• 来源：获取公开仓库，或在仓库私有时粘贴 Markdown。

重要的准备工作：

• 把决策或请求放在开头。一份以三页背景开场的评审材料不会被人认真评审。
• 明确标出待定问题。PDF 格式便于在打印稿上批注，但前提是问题清晰可见。
• 移除机密信息和客户标识符。工具不会把文档发送到任何地方，但评审材料往往会被转发。
• 在文件名中包含提交或文档版本。没有版本的评审记录日后很难核对。
• 如果文档包含任务列表，请检查渲染效果。GitHub 风格 Markdown 任务列表受支持，但长清单可能跨页拆分。请把相关条目放在一起。

获取流程不支持私有仓库。对于内部工作，粘贴或上传是实际可行的选择。这不是临时拼凑的变通方案，而是处理不应从公开 URL 读取的材料的预期方式。

5. 研讨会讲义与会议材料

放在仓库里的研讨会练习，默认读者有网络、有 GitHub 账号、有一台能用的笔记本。打印讲义则对这些一概不作要求。对于教程、会议演讲或课堂实验，PDF 往往是现场最可靠的副本。

推荐设置：

• 主题：精致讲义用商务，代码密集的实验用简洁。
• 目录：包含多个练习的讲义开启。
• 页面尺寸：匹配场地打印机。A4 和 Letter 都很常见；打印五十份之前请先确认。
• 来源：公开研讨会仓库直接获取，私有草稿则上传。

重要的准备工作：

• 按灰度设计。仅靠颜色区分章节的主题，在黑白打印机上会失去这种区分。
• 代码行控制在约 80 个字符以内。讲义是在一臂距离外阅读的，而不是在 27 英寸显示器上。
• 如果读者需要最新版本，请添加实时仓库的短链接或二维码。PDF 是稳定副本，仓库是持续更新的版本。
• 检查页数。40 页的讲义与 6 页的练习单是两种不同的产物。用目录和标题判断哪些内容应当保留。
• 活动前先打印一份。屏幕上看起来没问题的浏览器打印设置，在场地打印机上可能产生不同的边距。

应用的打印样式表专为清晰分页而设计，但它无法预知某台打印机如何处理边距。一次试打印仍然是最好的质量检查。

6. 基金、作品集与求职申请

申请材料常常要求把项目概览、技术说明或作品集样例作为单个附件提交。README PDF 在这里很适用，因为它以审阅者无需 GitHub 账号即可打开的形式，展示项目自身的文档。

推荐设置：

• 主题：面向一般受众用商务，研究导向的申请用学术。
• 目录：超过几页的文档开启。
• 页面尺寸：遵循申请说明。
• 来源：获取公开仓库，或在项目私有时粘贴 Markdown。

重要的准备工作：

• 把最相关的项目放在最前面。申请审阅者可能只读前两页。
• 移除没有实际含义的徽章。一整墙的构建徽章在作品集附件里只是噪音。
• 确保截图和图表有替代文本，并且确实能显示。损坏的图片比没有图片更糟。
• 检查 PDF 中的链接是否可点击。无法点进在线项目的审阅者会丢失上下文。
• 保持文件大小合理。图片过多的大型 PDF 可能触及申请门户的上传上限。

这也是商务主题的衬线字体能发挥作用的场景：它可以让技术项目读起来像一份专业文档，而不是仓库内容的原始倾倒。内容仍然必须撑起申请本身；主题只负责设定语域。

7. 审计与合规快照

有时 PDF 的目的并不是供人从头读到尾，而是证明文档在某个日期是这样写的。描述访问控制、数据处理或操作流程的 README，在被捕获为不可变产物后，可以成为审计材料的有用组成部分。

推荐设置：

• 主题：简洁。
• 目录：长文档开启。
• 文件名：包含仓库、提交和捕获日期。
• 来源：获取公开仓库，或粘贴经过审阅的准确 Markdown。

重要的准备工作：

• 记录来源版本。没有提交引用的 PDF 证据力较弱，因为底层 README 可能变化。
• 不要把 PDF 当作记录系统。它是文档的快照，不能替代日志、政策或签署证明。
• 检查文档是否包含机密信息、内部主机名或个人数据。审计材料的分发范围往往比原仓库更广。
• 把 Markdown 源文件与 PDF 放在一起。如果有人质疑捕获内容，源文件可以说明产物是如何生成的。
• 源文件变化时重新导出。文件名很新但内容过期的 PDF，比明显标明日期的旧 PDF 更糟。

PDF 不合适的情况

PDF 是分发格式，不是协作格式。以下情况它并不合适：

• 文档每天变化，读者需要最新版本。请改为链接到仓库，或按计划生成 PDF。
• 内容依赖交互元素、实时数据或嵌入视频。PDF 会把这一切压平。
• 仓库是私有的，而收件人需要浏览源码。PDF 给他们的是快照，不是访问权限。
• 文档只是很短的单页，在仓库中阅读体验已经很好。多这一步可能不值得。
• 你需要带跟踪的评论和建议。请使用协作文档工具；PDF 批注不能替代评审工作流。

这个工具刻意不做一个文档平台。它把你已经拥有的文档转换成便于携带的版本。知道何时不该用它，也是用好它的一部分。

五分钟飞行前检查清单

检查项	为什么重要
来源是正确的仓库或文件	项目名称错误的 PDF 比没有 PDF 更糟
标题层级一致	决定目录和页面结构
图片可解析	仓库相对路径需要先获取仓库
代码行不过宽	过宽代码块是最常见的裁切问题
表格适配页面	八列表格在 A4 上很少能完好呈现
链接有意义	blob 链接和外部链接在离线时仍应说得通
已移除机密文本	尽管转换在本地完成，PDF 仍可被转发
主题匹配受众	工程用简洁，客户用商务，论述用学术
页面尺寸匹配收件人	A4 与 Letter 会改变分页
文件名包含版本	让产物可追溯

主题速查表

• 简洁——规格文档、技术 README、代码密集讲义、审计。
• 商务——客户交付、提案、研讨会材料、作品集附件。
• 学术——课程包、论文、长篇论述、研究申请。
• 深色——导出前的屏幕审阅；打印样式表会为纸张将其调亮。

如果拿不准，从简洁开始，导出一份，在手机上或打印纸上阅读。在大显示器上最好看的主题，未必在一臂距离外最易读。

包含打印设置与故障排查的完整流程，请参阅如何将 GitHub README 转换为 PDF。想进一步了解四款主题，请参阅简洁、商务、学术与深色主题对比。