如何将 Markdown (MD) 转换为 PDF 用于发布
为什么 Markdown 作者需要 PDF 输出
Markdown 是技术作者、开发人员和博主的首选格式，他们希望专注于内容，而不是与文字处理器搏斗。文件体积小，版本控制清晰，即使是原始格式，语法也易于阅读。然而，当你需要向客户提交内容、呈交报告或发布一份精美的文档时，问题就出现了。普通的 .md 文件在不同编辑器中渲染效果各异，而且大多数非技术接收者根本不知道如何打开它们。 PDF 解决了这个问题。PDF 在每个设备上渲染效果一致，嵌入字体，保留你的标题层级结构，并且打印时不会出现格式意外。一份在 VS Code 中看起来完美的 40 页技术规范，可以作为单个、独立的文件发送到客户的收件箱，他们可以在任何浏览器或 PDF 阅读器中打开，无需安装任何东西。 不过，转换过程并非总是轻而易举。Markdown 本身没有关于分页符、边距或字体大小的标准——这些决定取决于处理它的渲染器。从“带星号的文本”到“可供打印的 PDF”之间的鸿沟，正是本指南要涵盖的内容，包括 CocoConvert 这类工具的适用范围，以及你何时可能需要更专业的工具。
MD 到 PDF 转换过程中发生了什么
理解其工作流程有助于你预测并解决输出问题。将 Markdown 转换为 PDF 实际上是一个幕后分两步进行的过程，即使有些工具将其隐藏在一个按钮后面。 第一步：Markdown 被解析成一种中间格式——几乎总是 HTML。每个标题都变成 `<h1>` 到 `<h6>` 标签，粗体文本变成 `<strong>`，代码块变成 `<pre><code>` 元素，等等。这一步的质量取决于解析器支持哪种 Markdown 方言。CommonMark 是最标准化的规范。GitHub Flavored Markdown (GFM) 增加了表格、任务列表和删除线。如果你的文档使用了 GFM 特性，例如管道表格，而转换器只处理 CommonMark，那么这些表格在输出中将显示为原始的管道字符。 第二步：HTML 使用无头浏览器引擎（如基于 Chromium 的 Puppeteer 工具）或专用 PDF 库渲染成 PDF。这一步应用 CSS 来处理排版、间距和页面布局。对于 A4 或信纸，通常将每边边距设置为 20–25 毫米。代码块会使用等宽字体。如果工具使用合理的默认样式表，结果无需任何配置就能看起来很专业。 实际意义是：如果你的 PDF 输出看起来有问题，通常是这两个步骤中的一个出了 bug——要么 Markdown 没有被正确解析，要么渲染时应用的 CSS 产生了意想不到的间距或字体选择。
使用 CocoConvert 进行快速 MD 到 PDF 转换
对于简单的文档——README 文件、会议记录、短报告、文档页面——CocoConvert 的 [MD 到 PDF 转换器](/convert/md-to-pdf) 可以轻松搞定，无需安装任何软件或掌握命令行知识。 过程分三步。首先，将你的 .md 文件拖到转换器上，或点击文件选择器进行上传。支持最大 25 MB 的文件，这涵盖了绝大多数 Markdown 文档（一份没有嵌入图片的 10,000 字文档通常小于 100 KB）。其次，点击“转换”。该工具解析 CommonMark 和 GFM 语法，包括带语言提示的围栏代码块、管道表格和内联 HTML。第三，下载生成的 PDF。 默认输出使用 A4 页面大小，20 毫米边距，11 磅可读的无衬线正文字体，以及代码块中的语法高亮。标题从 24 磅 (H1) 缩放到 13 磅 (H6)。这些默认设置适用于大多数文档和报告。 这里要诚实地指出局限性：CocoConvert 目前不支持自定义 CSS 注入、YAML Front Matter 处理或 LaTeX 数学符号（例如，`$E = mc^2$` 将显示为字面文本，而不是渲染的方程）。如果你的文档包含数学公式，使用带有 LaTeX 后端的 Pandoc 或支持 MathJax 的转换器会得到更好的结果。同样，如果你需要精确控制分页符——例如，在每个 H2 之前强制分页——命令行工作流程会给你更多控制权。
转换前准备你的 Markdown 文件
转换前花几分钟做些准备，可以避免最常见的输出问题。 **检查你的标题结构。** 如果文档有多个 H1 标题，生成的 PDF 中会有多行共享相同的超大字体，看起来没有结构。文档标题使用一个 H1，主要部分使用 H2，子部分使用 H3。大多数 Markdown linter（markdownlint 规则 MD025）会自动标记多个 H1。 **谨慎处理图片。** 如果你的 .md 文件使用相对路径引用图片，例如 ``，当文件单独上传到基于网络的转换器时，这些路径会失效。要么将图片作为 Base64 数据 URI 直接嵌入到 Markdown 中，要么使用指向公共可访问图片的绝对 URL（例如，``）。对于包含 5-10 张图片的文档，手动转换为 Base64 会很繁琐——如果你的转换器支持压缩包上传，可以考虑将 .md 文件及其图片文件夹一起打包上传，或者对于图片较多的文档，使用像 Pandoc 这样的本地工具。 **删除或替换不支持的语法。** 如果你的文件使用了 Hugo 短代码、Obsidian 标注（`> [!NOTE]`）或其他非标准扩展，在上传前请将其删除或转换为标准 Markdown 等价形式。Obsidian 标注可以用简单的块引用替换；Hugo 的 `{{< figure >}}` 标签可以用标准的 `![]()` 图片引用替换。 **检查行尾符。** Windows 风格的 CRLF 行尾符有时会在某些解析器中导致段落间距问题。通过快速 `dos2unix` 转换文件，或者从编辑器中以 LF 行尾符保存，可以消除这个变量。
何时使用 Pandoc（或与 CocoConvert 结合使用）
Pandoc 是一个免费、开源的命令行工具，它处理 Markdown 到 PDF 的转换，其可配置性远超任何网页工具。知道何时使用它能节省时间。 安装 Pandoc 和 LaTeX 发行版（Linux/Mac 上使用 TeX Live，Windows 上使用 MiKTeX），然后运行： ``` pandoc report.md -o report.pdf --pdf-engine=xelatex -V geometry:margin=1in -V fontsize=12pt ``` 这个简单的命令将 `report.md` 转换为一个 PDF，具有 1 英寸边距和 12 磅正文文本。添加 `--toc` 会自动生成目录。`-V` 标志将变量传递给 LaTeX 模板——你可以设置 `mainfont`、`monofont`、`papersize`、`linestretch` 和数十个其他参数。 对于数学公式繁多的文档，带有 XeLaTeX 的 Pandoc 是正确的工具——它能原生渲染 LaTeX 方程。对于需要自定义封面页、页眉页脚或精确控制孤行/寡行的文档，LaTeX 模板能提供完整的排版控制。 权衡之下是设置时间。安装 TeX Live 需要 3–5 GB 的磁盘空间和 15–30 分钟。调试 LaTeX 模板错误需要熟悉 LaTeX 语法。对于截止日期前晚上 11 点的一次性 README 转换，CocoConvert 是更快的选择。对于季度发布的 200 页技术手册，投入 Pandoc + LaTeX 工作流程，在第二或第三版之后就能看到回报。 这些工具并非互相排斥。一个合理的工作流程是：使用 CocoConvert 进行快速预览和分享草稿，然后将最终版本通过 Pandoc 和精美模板进行处理，以生成发布输出。
常见转换问题排查
**表格显示为纯文本。** 这通常意味着转换器使用的是只支持 CommonMark 的解析器，不支持 GFM 管道表格。请检查你的表格语法是否正确——每行需要相同数量的管道字符，并且分隔行（带破折号的那行）必须存在。如果转换器支持 GFM，正确格式化的表格将能渲染；如果不支持，请切换到支持 GFM 的工具，或者将表格转换为 HTML `<table>` 块，大多数 Markdown 解析器会原样通过 HTML 块。 **代码块失去缩进。** 这是一个字体问题——PDF 渲染器为代码回退使用了比例字体。检查转换器是否为 `<pre>` 元素应用了等宽字体。如果你使用 Pandoc，添加 `--variable monofont='Courier New'` 以强制使用特定的等宽字体。 **图片缺失。** 几乎总是路径解析问题。请参阅上面的准备部分。确认图片 URL 返回 HTTP 200 且没有进行身份验证。 **PDF 没有页码。** 基于网络的转换器通常不添加页眉页脚，因为这需要带有计数器支持的 CSS `@page` 规则，而并非所有 PDF 引擎都能一致处理。如果你需要页码，带有 LaTeX 后端的 Pandoc 默认会添加，或者你可以在 Adobe Acrobat 中进行 PDF 后期处理（工具 > 编辑 PDF > 页眉和页脚 > 添加）。 **代码块中的长行溢出页面边距。** 这是一个换行问题。在 CSS 中，`pre { white-space: pre-wrap; }` 可以解决，但在大多数网络转换器中你无法注入 CSS。解决方法是在转换前手动将源文件中的长行换行，将每行保持在 80-90 个字符以下。
选择正确的发布设置
“发布”一词涵盖了广泛的输出形式，不同形式的最佳设置差异很大。 **用于网页或电子邮件分发：** A4 或美国信纸尺寸，20–25 毫米边距，11–12 磅正文。嵌入所有字体以确保在接收方机器上一致渲染。如果文件大小很重要——例如，你正在通过电子邮件附件发送，有 10 MB 的限制——避免以全分辨率嵌入大图像文件。在将图片包含在 Markdown 源中之前，将其大小调整为 150–200 DPI。 **用于打印：** 对于任何位图图像，至少使用 300 DPI。边距应更宽——25–30 毫米——以应对文档需要装订的情况。如果通过专业服务打印，请询问他们是否需要 PDF/X-1a 或 PDF/X-4 兼容性；大多数网络转换器生成的是标准 PDF 1.4 或 1.5，而不是用于印刷生产的 PDF/X 变体。 **用于电子阅读器和平板电脑：** 考虑 PDF 是否真的是正确的格式。EPUB 在小屏幕上处理可重排文本效果更好。话虽如此，如果必须使用 PDF，较小的页面尺寸（大约 6×9 英寸，类似于平装书）在平板电脑上会比缩小尺寸的 A4 页面提供更好的阅读体验。 **用于技术文档门户：** 许多文档平台（ReadTheDocs, GitBook, Docusaurus）都有自己基于 Chromium 或 WeasyPrint 构建的 PDF 导出管道。如果你已经在使用这些平台之一，它们的原生导出会比单独转换 .md 文件更好地尊重你网站的主题和导航结构。 对于大多数日常发布需求——分享一份精美报告、分发规范文档或存档 README——直接通过 [CocoConvert 的 MD 到 PDF 工具](/convert/md-to-pdf) 使用默认设置进行转换，能在不到一分钟内生成清晰、可读的结果。