Pandoc 命令速查表 - 文档格式转换命令大全
把文档从一种格式复制粘贴到另一种，通常会把辛苦调好的结构一并毁掉。Pandoc 基于统一的文档模型转换，标题、表格、引用都能保住。本表覆盖 Markdown/HTML/PDF/DOCX/EPUB 互转、PDF 中文与字体设置、模板样式、幻灯片、电子书，以及引用文献与数学公式。当你的 CMS、wiki 或客户只认某一种格式、而你习惯用另一种写作时，用它一次转换到位。读完能在不重排版式的前提下跨格式搬运文档。
典型使用场景
面向需要一份源文件同时产出多种格式的技术写作者与文档维护者：Markdown 写稿，投递到 Word 走评审、发 PDF 走归档、发 HTML 走官网、发幻灯片走分享。本表按「格式对 / 元数据对 / 版式对 / 参考文献对」四层组织：格式用 -f/-t 与 -o，元数据用 -V 与 --metadata-file，版式用 --reference-doc / --template / --self-contained，文献用 --citeproc 与 --csl。适合做「一份 Markdown 统一输出」的内容流水线，或排查输出丢失样式、目录、数学公式不渲染这类问题。
基础转换 8
pandoc input.md -o output.htmlpandoc input.md -o output.pdfpandoc input.md -o output.docxpandoc input.html -o output.mdpandoc input.docx -o output.mdpandoc input.md -o output.epubpandoc -f markdown -t html5 input.md -o output.htmlpandoc input.md -o output.orgPDF 高级选项 5
pandoc input.md -o output.pdf --pdf-engine=xelatexpandoc input.md -o output.pdf -V mainfont="Noto Sans CJK SC"pandoc input.md -o output.pdf --tocpandoc input.md -o output.pdf --toc --toc-depth=3pandoc input.md -o output.pdf -V geometry:margin=1in模板与样式 5
pandoc -s input.md -o output.htmlpandoc input.md --template=mytemplate.html -o output.htmlpandoc input.md --css=style.css --self-contained -o output.htmlpandoc input.md -H header.html -o output.htmlpandoc -o template.html --print-default-template html5元数据与幻灯片 5
pandoc input.md -V title="标题" -V author="作者" -o output.pdfpandoc input.md -t beamer -o output.pdfpandoc input.md -t slidy -o output.htmlpandoc input.md -t revealjs -o output.htmlpandoc input.md -f markdown -t plain引用文献与公式 Citations & Math 6
pandoc input.md --citeproc -o output.pdfpandoc input.md --bibliography=refs.bib --citeproc -o output.pdfpandoc input.md --csl=ieee.csl -o output.pdfpandoc input.md --mathjax -o output.htmlpandoc input.md --katex -o output.htmlpandoc --list-extensions markdown常用参数 9
--highlight-style=tango--number-sections--standalone / -s--metadata-file=meta.yaml--filter=pandoc-filter-V key=value--wrap=auto--columns=80--reference-doc=template.docx参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
-s / --standalone | 生成完整文档（含 head 与 body 包裹）；不加时只输出文档片段 | pandoc -s input.md -o output.html |
--reference-doc=template.docx | 用一份 Word 参考文档的样式控制 docx 输出，解决标题/代码字体走默认样式的问题 | --reference-doc=template.docx |
--self-contained + --css | 把 CSS 内嵌进单个 HTML 文件，便于离线分发 | pandoc input.md --css=style.css --self-contained -o output.html |
--citeproc + --bibliography / --csl | 启用引用处理并指定文献库与引用样式，缺一则引用原样输出 | pandoc input.md --csl=ieee.csl -o output.pdf |
易错点与避坑指南
现象转出的 Word 里标题、代码块全是默认样式，和源文件排版完全不同。
原因docx writer 不继承外部样式，只用内置默认样式或参考文档。
处置先导出一份 docx 改好样式，命名为模板，再加 --reference-doc=template.docx。
现象生成的 HTML 打开后没有样式，甚至在浏览器里直接显示成裸片段。
原因只输出了文档片段，或 CSS 仍以外链方式引用而文件没一起拷过去。
处置加 -s 生成完整文档，需要单文件时加 --self-contained --css=style.css。
现象PDF 里的中文变成空白或方块。
原因默认 pdflatex 引擎不支持系统字体与中文。
处置改用 --pdf-engine=xelatex 并用 -V mainfont="Noto Sans CJK SC" 指定字体。
现象文档里的 [@key] 原样出现在输出中，参考文献列表是空的。
原因没启用 --citeproc，或未提供文献库文件。
处置加 --citeproc --bibliography=refs.bib，并用 --csl 指定引用样式。
排障路径
1先确认当前版本支持哪些扩展
pandoc --list-extensions markdown语法行为随扩展集变化，确认列表后再判断某个写法是否被识别。
2导出默认模板作为改造起点
pandoc -o template.html --print-default-template html5在默认模板上加自定义块，再用 --template=mytemplate.html 应用。
3验证某个源文件实际被解析成了什么结构
pandoc -f markdown -t plain转成纯文本能立刻看出标题层级、列表与表格是否被正确识别。
命令示例
一份 Markdown 产出多种格式
pandoc input.md -o output.html
pandoc input.md -o output.docx
pandoc input.md -o output.epub
pandoc -f markdown -t html5 input.md -o output.html默认按扩展名推断格式，-f/-t 用于显式指定；输入侧同理可做 pandoc input.html -o output.md 这类反向转换。
中文 PDF 的引擎与字体
pandoc input.md -o output.pdf --pdf-engine=xelatex -V mainfont="Noto Sans CJK SC"
pandoc input.md -o output.pdf --toc --toc-depth=3 -V geometry:margin=1in引擎与字体要同时给；-V 传的是模板变量，页边距与目录层级都从这里控制。
单文件 HTML 与自定义模板
pandoc -s input.md -o output.html
pandoc input.md --css=style.css --self-contained -o output.html
pandoc input.md -H header.html -o output.html
pandoc -o template.html --print-default-template html5
pandoc input.md --template=mytemplate.html -o output.html模板改造的起点是导出的默认模板；-H 插入 head 片段，--self-contained 让 CSS 内嵌。
引用文献、公式与扩展自查
pandoc input.md --bibliography=refs.bib --citeproc -o output.pdf
pandoc input.md --csl=ieee.csl --citeproc -o output.pdf
pandoc input.md --katex -o output.html
pandoc --list-extensions markdown文献库、CSL 样式、citeproc 三者齐备引用才会渲染；公式也可改用 --mathjax 走 MathJax。
常见坑与注意事项
- 不加 -s / --standalone 时输出只是文档片段，浏览器打开会没有 head 与 body 结构。
- 生成中文 PDF 必须同时给 --pdf-engine=xelatex 和中文字体，只改引擎不改字体仍会出方块。
- docx 样式丢失要靠 --reference-doc 提供参考文档，不要靠反复手调 Markdown 语法。
- 引用只在 --citeproc、--bibliography、--csl 齐备时才会被渲染，缺一项就会原样留下 [@key]。
- -V key=value 里的值必须用引号包裹，尤其是含空格的标题与作者字段，否则 shell 会把它拆成多个参数。
提示
- 中文 PDF 必须用 xelatex 引擎并指定中文字体，否则乱码。
- Markdown 转 Word 后样式可能丢失，建议先转 HTML 再转 DOCX 保真度更高。
- pandoc --list-output-formats 查看所有支持的输出格式。
常见问题
为什么输出的 HTML 看起来是裸片段？
因为你没加 -s。默认 pandoc 只输出文档片段，不含 head 与 body 包裹，用 pandoc -s input.md -o output.html 生成独立 HTML 即可。需要自定义 head 内容时用 pandoc input.md -H header.html -o output.html，把自己的标签插进 head；想让样式跟着文件走则加 --css=style.css --self-contained 把 CSS 内嵌成单文件。
转出的 Word 样式全变了，怎么保住排版？
因为 docx 输出走的是 Word 的样式集，而不是 Markdown 的写法。用 --reference-doc=template.docx 提供一份参考文档，pandoc 会沿用它的标题、正文、代码块样式；这份模板可以先从已有文档另存得到。要改得动模板本身，就先 pandoc -o template.html --print-default-template html5 导出默认模板作为改造起点，再配合 --template=mytemplate.html 使用。
PDF 里的中文变成空白或方块，怎么处理？
两个变量一起确认：引擎与字体。引擎用 pandoc input.md -o output.pdf --pdf-engine=xelatex，它能处理系统字体；字体再显式指定，例如 -V mainfont="Noto Sans CJK SC"。只换引擎不指定字体在缺少对应字体的机器上仍然出方块。页边距这类排版项用 -V geometry:margin=1in，想带目录再加 --toc，层级用 --toc-depth=3 限制。
文档里的引用为什么原样输出成 [@key]？
因为引用处理没开，或者开了但缺文献库或样式文件。pandoc input.md --citeproc -o output.pdf 会启用引用处理，接着用 --bibliography=refs.bib 指定 BibTeX 文献库、--csl=ieee.csl 指定引用格式；缺一则引用不会被渲染，参考文献列表也是空的。另外可以先用 pandoc --list-extensions markdown 确认当前版本支持哪些扩展，再判断是不是扩展缺失。
同一份 Markdown 要出多种格式，元数据该放哪？
两种方式。简单场景直接用 -V key=value 逐个传，例如 -V title="标题" -V author="作者"；条目一多就写成 YAML 文件用 --metadata-file=meta.yaml 统一维护，避免命令行里堆一长串变量。变量最终只对模板可见，所以样式、页边距这些也走同一条通路，例如 -V geometry:margin=1in。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。