Markdown 转 PDF 完全指南：从基础到自动化

为什么需要将 Markdown 转换为 PDF？

Markdown 以其简洁的语法和易读性成为许多开发者、写作者的首选格式。然而，在正式分享、打印或提交给客户时，PDF 的通用性和固定排版更加可靠。掌握 Markdown 转 PDF 的技巧，能让你既享受写作的流畅，又获得专业的输出。

主流转换工具与方案

1. Pandoc：瑞士军刀般的转换利器

Pandoc 是最强大的文档转换工具，支持几乎所有标记格式。安装后，一条命令即可完成转换：

pandoc input.md -o output.pdf --pdf-engine=xelatex -V mainfont='Microsoft YaHei'

其中 --pdf-engine 指定引擎（建议 xelatex 以支持中文字体），-V mainfont 设置字体。你也可以编写 YAML 元数据块来自定义标题、作者等。

2. Typora：所见即所得，一键导出

Typora 是一款流行的 Markdown 编辑器，内置 PDF 导出功能。只需点击“文件”→“导出”→“PDF”，即可获得与编辑界面基本一致的结果。缺点是定制能力有限，适合快速导出。

3. Visual Studio Code 扩展

安装扩展如“Markdown PDF”或“vscode-pandoc”，可在 VS Code 中直接右键预览并导出。扩展通常支持自定义样式表，通过修改 CSS 控制 PDF 外观。

4. 在线转换工具

如 Markdown to PDF、Md2PDF 等网站，适合临时少量转换。注意隐私风险，敏感文档不建议使用。

高级定制：让 PDF 更专业

使用模板与 CSS

Pandoc 支持 --template 参数指定 LaTeX 模板，可彻底控制页眉、页脚、封面等。若用 --pdf-engine=wkhtmltopdf，则可以通过 -c custom.css 应用 CSS 样式。

添加代码块语法高亮

pandoc code.md -o code.pdf --highlight-style tango --pdf-engine=xelatex

--highlight-style 参数可选 pygments、tango、espresso 等。

批量转换与自动化

使用 Shell 脚本或 Makefile 批量处理：

#!/bin/bash
for file in *.md; do
  pandoc "$file" -o "${file%.md}.pdf" --pdf-engine=xelatex
done

配合 GitHub Actions 可在推送时自动生成 PDF 并发布到 Release。

常见问题与解决

• 中文字体显示异常：务必使用 xelatex 或 lualatex 引擎，并通过 -V mainfont 明确指定系统支持的中文字体。
• 图表与数学公式：Pandoc 支持 LaTeX 数学公式（$...$），需要安装 texlive-latex-extra。Mermaid 图表需先转换为图片。
• PDF 文件过大：使用 --pdf-engine-opt=--reduce-pdf 或后期压缩工具如 Ghostscript。

结语

从简单的 Typora 导出到高度自定义的 Pandoc 脚本，Markdown 转 PDF 的生态已经非常成熟。选择最适合你工作流的方法，让文档处理更高效、更优雅。