如何将 GitHub README 转换为 PDF（免费、无需登录）

README 是为浏览器而写的：它可以滚动、可以外链，并默认读者能在仓库里四处点击。可一旦你需要把文档发给客户、附在作业中、为某个版本存档，或交给一个不会克隆仓库的人，PDF 才是真正便于传递的格式。

直接打印 GitHub 页面通常会一团糟。站点导航、侧边栏和页脚会一并被打印出来；过宽的代码块会被裁掉；相对路径的图片会失效，因为浏览器已不再从仓库根目录读取内容；长表格会在分页处被生硬地切断。md2pdf 正是为解决这些具体问题而生，而且不需要你注册账号，也不要求你把源文件上传到服务器。

本指南将走完整个流程，从粘贴仓库 URL 到检查导出的 PDF，并解释工具在每一步都做了什么。

为什么浏览器自带的“打印”按钮不够用

GitHub 的网页界面是一个 Web 应用，而不是一套打印样式表。当你在仓库页面按下 Ctrl+P 时，浏览器会尝试打印整个页面：页头、文件树、“关于”侧边栏、反馈组件，以及布局里恰好存在的其他所有内容。其中一部分可以通过自定义打印样式表隐藏，但你无法从外部修改 GitHub 的标记结构。

另外还有三个反复出现的问题：

• 相对图片路径。 README 中写着 ![diagram](docs/architecture.png)，在 GitHub 上能正常显示，是因为图片会基于仓库进行解析。而打印出来的浏览器页面没有可靠的仓库上下文，图片可能就此消失。
• 过宽的代码与表格。 代码块和对比表格往往比打印页面更宽。若没有针对打印的规则，它们要么被缩小到难以辨认，要么被直接裁切。
• 分页。 标题、代码块和表格行都需要避免尴尬的断页。浏览器原生的打印功能很少能处理好这一点。

md2pdf 会获取 README 的原始 Markdown，解析仓库相对 URL，以 GitHub 风格 Markdown 渲染，净化结果，并在浏览器打印对话框打开前应用打印样式表。输出仍由浏览器原生的“另存为 PDF”引擎生成，但它接收到的文档已经过清理。

md2pdf 做了哪些改变

整个转换流程都在浏览器中运行。具体来说：

1. 你提供一个公开 GitHub 仓库 URL、一个本地 Markdown 文件，或一段粘贴的 Markdown。
2. 如果是仓库，应用会发现默认分支，并尝试一组常见的 README 文件名，包括 .github/ 目录中的文件。
3. 相对图片路径会被改写为 raw.githubusercontent.com，文档链接会被改写为 GitHub blob 视图。
4. Markdown 以 GFM 支持渲染：表格、任务列表、删除线、围栏代码和自动链接。
5. HTML 在进入预览之前会先经 DOMPurify 净化。
6. 当文档包含至少三个标题时，会生成目录。
7. 应用所选主题的打印样式表，随后浏览器打开打印对话框。

没有任何文件被上传。唯一的对外请求是匿名读取你指定的公开仓库，以及用于发现默认分支的 GitHub API 调用。此版本不支持私有仓库。

开始之前

你需要：

• 一个公开的 GitHub 仓库，或一个本地 Markdown 文件，或一段可粘贴的 Markdown。
• 一款现代浏览器。Chrome、Edge、Firefox 和 Safari 的打印对话框都支持“另存为 PDF”。
• 短文档大约两分钟；如果你打算逐页检查 PDF，则需要更久。

如果仓库是私有的，获取会失败。手动方案仍然可用：复制 README 文本，粘贴到编辑器中，并使用绝对图片 URL。

第 1 步：把仓库交给工具

打开转换器，将仓库 URL 粘贴到 GitHub 仓库 URL 字段。md2pdf 接受的并不只是标准 URL：

https://github.com/owner/repo
https://github.com/owner/repo.git
github.com/owner/repo
owner/repo
https://github.com/owner/repo/tree/main/docs
https://github.com/owner/repo/blob/main/README.md

以上所有形式都会解析为同一个 owner/repo 组合。从终端或聊天消息中复制时，无协议 URL 和 owner/repo 简写都很方便。额外路径段是为方便而接受的，但会被忽略：应用仍然读取默认分支上的仓库根级 README，而不是 URL 中显示的嵌套文件。如果你需要的正是那个嵌套文件，请直接粘贴它的 Markdown。

点击 获取 或按 Enter。如果字段为空，应用会告诉你它期望什么，而不是默默无反应。

第 2 步：让它获取并解析 README

应用首先向 GitHub API 查询仓库的默认分支，然后针对该分支尝试一系列 README 文件名，包括常见的大小写变体和 .github/README.md 位置。如果 API 触发限流，原始文件获取仍可继续——这正是临时的 API 故障并不总会中断流程的原因。

Markdown 到达后，预览会随之更新。此时应检查三件事：

• 图片。 仓库相对图片应当正常显示。如果某张没有出现，它可能指向私有资源、不存在的路径，或禁止热链的绝对 URL。
• 代码块。 带语言标注的围栏代码块会按代码样式渲染。超宽行在预览中可以滚动，但仍需在打印时检查。
• 链接。 文档链接会被改写为 GitHub blob 视图，以便在 PDF 中仍然有意义。外部链接在预览中会在新标签页打开。

如果某张图片加载失败，md2pdf 会将其标记为损坏并继续。导出不会因为一个徽章不可用而失败。这是有意为之：缺失的徽章通常没有文档其余部分重要。

第 3 步：选择与文档匹配的主题

共有四款打印主题：

• 简洁是默认主题。它使用中性的无衬线字体，是规格文档、技术 README 和代码密集文档最稳妥的选择。
• 商务使用衬线字体和深色代码块，适合报告、提案和面向客户交付的材料。
• 学术使用两端对齐的衬线页面和浅色代码样式，专为长篇论述、课程读本和论文式提交材料而设计。
• 深色是以屏幕阅读为先的主题。预览采用深色背景，便于舒适阅读；打印样式表则强制使用浅色墨迹和浅色代码背景，确保 PDF 清晰可读。

如需更深入的比较，请参阅简洁、商务、学术与深色主题对比。多数首次导出建议从简洁开始，只有当文档有明确的受众期待时才切换。

第 4 步：判断目录是否有帮助

自动目录默认启用，当文档包含三个或更多标题时生成。它使用稳定且唯一的标题锚点，因此条目会在预览中链接到正确的章节。

以下情况请保留目录：

• 文档超过几页。
• 读者需要跳转到特定章节。
• 你要把 PDF 交给可能只打印其中一部分的人。

以下情况请关闭目录：

• README 很短，目录块带来的干扰多于导航价值。
• 文档已有手写目录。
• 你正在制作单页讲义。

该开关同时影响预览和打印输出。没有单独的“仅 PDF”设置。

第 5 步：用正确的设置打印为 PDF

在实时预览面板中点击 下载 / 打印 PDF。应用会调用浏览器的打印对话框。在对话框中：

1. 将目标设为另存为 PDF（或浏览器中的对应选项）。
2. 选择 A4 或 Letter，以匹配收件人所在地区。
3. 除非你有公司统一规范，否则边距保持默认。打印样式表已经设置了页面边距。
4. 首次尝试时缩放保持 100%。如果宽表格或代码块被裁切，请略微降低缩放比例，而不是缩小源文件中的字号。
5. 如果浏览器提供该选项，请启用背景图形。主题强调色、代码块背景和表头填充都依赖背景色。关闭后 PDF 仍可阅读，但商务和深色主题会失去部分视觉结构。
6. 除非你确实需要 URL 和页码，否则关闭浏览器的页眉和页脚。它们不属于文档设计的一部分。
7. 用描述性的文件名保存，例如 owner-repo-readme-2026-10.pdf。

具体标签因浏览器而异。在 Chrome 和 Edge 中，背景图形位于“更多设置”下；在 Firefox 中，请查找“打印背景”；Safari 提供的控件较少，保存前请先检查预览。

第 6 步：发送前检查 PDF

打开已保存的 PDF，扫描那些只有在打印中才会暴露的问题：

• 分页。 标题不应孤零零地留在页面底部。代码块、表格和图片不应从中间被拆开。
• 过宽内容。 过长的代码行和表格是最常见的溢出元凶。如果它们被裁切，请在源文件中缩短行长度，或降低打印缩放。
• 链接。 在 PDF 中点击几个链接。GitHub blob 链接应打开正确的文件视图。
• 图片。 确认图表和徽章都保留下来。缺失的私有资源不会在 PDF 中自行修复。
• 元数据。 文档标题和作者来自 README 以及浏览器的打印元数据设置，而不是专门的 PDF 元数据表单。请给文件起一个清晰的名字。
• 可读性。 以 100% 比例打印一页，确认正文阅读舒适。学术主题的两端对齐文本和商务主题的衬线字体，在纸上的观感可能与屏幕不同。

获取失败时

应用会将获取失败映射为可操作的提示。常见情况如下：

你看到的内容	通常意味着	该怎么办
仓库不存在或为私有	URL 有误，或仓库需要身份验证	检查 URL；如果仓库为私有，请手动粘贴 Markdown
未找到 README	仓库在默认分支、main 或 master 上没有 README	上传文件或粘贴 Markdown
触发 GitHub 限流	未认证 API 请求过多	等待约一分钟后重试；原始文件获取可能仍然可用
获取失败或超时	网络问题，或请求超过 15 秒超时	重试；手动粘贴方式仍然可用

如果获取失败，编辑器会保留你已经输入的内容。你可以切换到粘贴或上传模式，而不会丢失当前页面。

改用粘贴或上传

从 GitHub 获取很方便，但并非唯一入口。转换器还支持：

• 上传不超过 2 MB 的 .md、.markdown 或 .txt 文件。
• 粘贴 Markdown 到编辑器中。输入时，预览会在短暂防抖后重新渲染。
• 加载示例，查看表格、任务列表和代码块的处理效果。

需要注意：只有先获取过仓库，相对图片路径才能解析。上传或粘贴的 Markdown 没有仓库基准，因此在该模式下请使用绝对图片 URL。其余内容——标题、表格、代码、任务列表——工作方式完全相同。

五项改善每次导出的源文件级修正

PDF 的质量，取决于作为起点的 Markdown。以下调整会立刻见效：

1. 使用真正的标题层级。 章节从 ## 开始，子节用 ###，避免跳级。目录和打印样式表都依赖结构。
2. 为图片提供有用的替代文本。 这有利于无障碍访问，也能在图片无法加载时为 PDF 提供可读的兜底。
3. 为代码标注语言。 带语言标签的代码块比缩进代码渲染得更可预测，尤其在行很长时。
4. 保持表格窄小。 八列的表格在 A4 上不缩小就放不下。请把细节移入正文，或拆分表格。
5. 仓库资源优先使用相对路径。 md2pdf 会正确改写它们。指向本机或私有存储桶的绝对链接无法顺利保留。

隐私：什么会离开你的浏览器

md2pdf 不会上传你的 Markdown。渲染、净化、目录生成和 PDF 导出全部在本地完成。若从仓库获取，唯一的对外请求是针对公开 README 及其图片的匿名 GitHub 读取。转换过程没有账号、没有 Cookie，也没有分析统计。

当文档包含内部备注、客户名称或尚未发布的计划时，这一点尤为重要。你可以粘贴敏感 Markdown 并导出，而无需把文本发送给第三方转换服务。本地文件同样如此：文件由浏览器读取，而不是上传。

简要版

粘贴公开仓库 URL，点击获取，确认预览，选择主题，长文档保留目录，然后在启用背景图形的情况下打印为 PDF。发送文件前检查分页和过宽的代码块。如果获取失败，就粘贴或上传 Markdown 继续。

整个流程刻意做得平淡无奇：没有账号、没有队列、没有上传、没有服务器端渲染器。只有一个 README、一套打印样式表，以及一份可以随手交给别人的 PDF。