用 Pandoc 转换 Markdown、Word 与 PDF：模板、引用与批量处理

你手上有一份 Markdown 稿子，要同时交 Word 给编辑、PDF 给客户、HTML 放到文档站。手工复制到 Word 里调样式、再导出 PDF，重复几次就容易出现版本不一致。Pandoc 解决的正是这个问题：它以同一份 Markdown 为源文件，按扩展名推断输出格式，用一条命令生成 docx、PDF 或独立 HTML。下面按“准备环境—单文件转换—模板复用—引用处理—批量转换—抽查结果”的顺序，把一条能落地的流程走一遍。

先确认 Pandoc 和 PDF 引擎是否就位

Pandoc 本身是一个命令行文档转换工具，支持 Markdown、HTML、LaTeX、Word docx 等多种输入输出格式。安装后先在终端确认版本和可用格式：

pandoc --version
pandoc --list-output-formats

常见安装方式如下，按你的系统选一条即可：

# Windows（PowerShell，使用 winget）
winget install pandoc

# macOS（Homebrew）
brew install pandoc

# Debian / Ubuntu
sudo apt install pandoc

Word 和 HTML 输出只依赖 Pandoc 本身。PDF 不一样：Pandoc 生成 PDF 通常要借助外部排版引擎，常见组合是 LaTeX 引擎（如 xelatex、lualatex），也可以走 HTML 转 PDF 的引擎。你可以先用下面命令检查引擎是否存在：

xelatex --version
# 或者
weasyprint --version

如果只装 Pandoc 不装引擎，执行 PDF 输出时会直接报错。对中文文档来说，xelatex 配合中文字体是比较常见的路径；不想安装完整 LaTeX 发行版时，也可以先转成 docx，再用 Word 或 LibreOffice 导出 PDF，或者用 HTML 加 CSS 的方式生成 PDF。选哪条路，取决于你对排版精度的要求。

用一份 Markdown 生成三种交付格式

假设你的源文件叫 guide.md，先建一个输出目录：

mkdir -p out/docx out/pdf out/html

然后分别执行：

# Word
pandoc guide.md -o out/docx/guide.docx

# 独立 HTML（-s 表示生成完整 HTML 文件，而不是片段）
pandoc guide.md -s -o out/html/guide.html

# PDF，指定 xelatex 和中文字体
pandoc guide.md 
  --pdf-engine=xelatex 
  -V mainfont="Noto Serif CJK SC" 
  -o out/pdf/guide.pdf

这里需要替换的参数只有文件名和字体名：guide.md 换成你的源文件，Noto Serif CJK SC 换成你系统里已安装的中文字体。-o 后面的扩展名决定了输出格式，所以不必额外写 --to=docx；如果你想明确指定读写格式，可以用 --from markdown --to docx。

几个常用参数可以一起加上：

pandoc guide.md 
  --toc 
  --number-sections 
  --reference-doc=reference.docx 
  -o out/docx/guide.docx

--toc 生成目录，--number-sections 给标题编号，--reference-doc 指定 Word 模板。注意目录和编号在不同输出格式里的呈现方式不完全一样，Word 中的目录可能是静态列表，不一定会自动更新页码；交付前最好打开确认。

用 reference-doc 复用 Word 模板

如果你每次都要把 Word 的标题字体、正文行距、引用样式调一遍，说明你需要的是一份固定的 reference doc。Pandoc 可以导出一份默认模板：

pandoc --print-default-data-file reference.docx > reference.docx

用 Word 或 LibreOffice 打开 reference.docx，在“样式”面板里修改“正文”“标题 1”“标题 2”“引用”“源代码”等样式，调整字体、字号、行距、段前段后和颜色。修改时只动样式，不要在文档正文里写示例内容。保存后，转换时加上：

pandoc guide.md --reference-doc=reference.docx -o guide.docx

这样所有用这份模板转出的 Word 文件都会复用同一套样式。需要提醒的是，reference-doc 主要作用于 docx 和 ODT 输出，不会直接控制 PDF 的版面。PDF 的模板是另一套机制：LaTeX 引擎使用 LaTeX 模板，HTML 转 PDF 的引擎使用 CSS。你要把“Word 模板”和“PDF 模板”分开维护，不要指望一个 docx 模板同时决定 PDF 的页边距和字体。

如果你在 Markdown 里用了自定义段落样式，可以在 docx 模板中先定义同名样式，再用 Pandoc 的 custom-style 属性应用。例如：

::: {custom-style="提示框"}
这是一段需要套用“提示框”样式的文字。
:::

模板里没有对应样式时，Word 会回退到默认样式，所以自定义样式要先在模板中建好。

把元数据、目录和引用交给 Pandoc 处理

标题、作者、日期、语言这些信息可以写在 Markdown 文件开头的 YAML 元数据块里：

---
title: "产品使用手册"
author: "文档组"
date: "2025-06-01"
lang: "zh-CN"
bibliography: "refs.bib"
csl: "chinese-gb7714-2015-numeric.csl"
---

bibliography 指向你的文献库，csl 指向引文样式文件，路径按你的实际目录替换。正文中用 [@key] 插入引用，转换时加上 --citeproc，Pandoc 才会处理引用并生成参考文献列表：

pandoc guide.md 
  --citeproc 
  --bibliography=refs.bib 
  --csl=chinese-gb7714-2015-numeric.csl 
  -o out/pdf/guide.pdf

如果你在 YAML 里已经写了 bibliography 和 csl，命令行可以省略对应参数，但 --citeproc 仍然要显式加上。引用编号和参考文献表的样式由 CSL 文件决定，换一种期刊格式通常只需要换 CSL 文件，不必改正文里的引用标记。

PDF 输出时，中文断行、字体缺字和标点挤压是比较常见的检查点。用 xelatex 时，先确认 mainfont 或模板要求的中文字体变量指向已安装字体；如果输出里出现方框或乱码，优先检查字体名是否写对，而不是反复改 Markdown。

PDF 输出依赖排版引擎，先选一条稳的路径

PDF 不是 Pandoc 自己“画”出来的，它要把文档交给排版引擎。你可以按下面的思路选：

需要接近 LaTeX 的排版质量、公式和交叉引用较多：用 --pdf-engine=xelatex 或 lualatex，并配置中文字体。
不想安装大型 LaTeX 发行版：用 --pdf-engine=weasyprint，通过 HTML 和 CSS 控制版面，适合以文字、表格和简单图片为主的文档。
只是临时交付：先转 docx，在 Word 或 LibreOffice 里检查分页和页眉页脚，再导出 PDF。

对应的命令示例：

# LaTeX 引擎
pandoc guide.md --pdf-engine=xelatex -V mainfont="Noto Serif CJK SC" -o guide.pdf

# HTML 转 PDF 引擎
pandoc guide.md --pdf-engine=weasyprint -o guide.pdf

不同引擎对 CSS、页边距、分页和字体的支持不一样，同一份 Markdown 换引擎后版面可能明显变化。正式批量前，先用一份包含标题、表格、代码块、脚注和引用的样本跑一遍，确认引擎和模板组合稳定，再扩大到全部文件。

批量转换：先跑通一份，再循环整个目录

单文件命令稳定后，批量处理只是加一层循环。以下脚本把 src/ 下的所有 .md 转成 docx、PDF 和 HTML：

mkdir -p out/docx out/pdf out/html

for f in src/*.md; do
  base=$(basename "$f" .md)

  pandoc "$f" 
    --reference-doc=reference.docx 
    --toc 
    -o "out/docx/$base.docx"

  pandoc "$f" 
    --pdf-engine=xelatex 
    -V mainfont="Noto Serif CJK SC" 
    --toc 
    -o "out/pdf/$base.pdf"

  pandoc "$f" 
    -s 
    --toc 
    -o "out/html/$base.html"
done

在 Windows PowerShell 里可以写成：

New-Item -ItemType Directory -Force -Path outdocx, outpdf, outhtml | Out-Null

Get-ChildItem src*.md | ForEach-Object {
  $base = $_.BaseName

  pandoc $_.FullName --reference-doc=reference.docx --toc -o "outdocx$base.docx"

  pandoc $_.FullName --pdf-engine=xelatex -V mainfont="Noto Serif CJK SC" --toc -o "outpdf$base.pdf"

  pandoc $_.FullName -s --toc -o "outhtml$base.html"
}

批量脚本里要特别注意文件名带空格的情况，路径变量要加引号。转换完成后，不要只看终端有没有报错，至少做三类抽查：

数量对不对：输出目录里的文件数是否和源文件数一致。
空文件有没有：用 find out -type f -size 0 快速找出零字节文件。
内容有没有坏：随机打开几份，重点看目录、表格、代码块、引用编号和图片位置。

复杂样式和表格可能丢失，先用小样本验证

Pandoc 的转换不是“像素级复制”。它把文档解析成一种中间结构，再写到目标格式，因此 Word 里的浮动文本框、复杂合并单元格、精确分页、页眉页脚差异、艺术字和部分形状，通常不会原样保留。表格是最容易出问题的地方：Markdown 的表格语法对合并单元格支持有限，从 Word 转成 Markdown 再转回去，复杂表头可能被拆成普通行。代码块的高亮和换行、脚注编号、多级列表的缩进，也可能因输出格式不同而变化。

比较稳妥的做法是先做一份“压力测试”样本，里面放上你实际文档中最复杂的元素：