Pandoc 通用文档转换 SOP

信源: https://pandoc.org/MANUAL.html | 版本: pandoc 3.x

一、简介

Pandoc 是 Haskell 编写的通用文档转换器，支持 51 种输入格式 × 75 种输出格式（含 37 种双向互转），是文档转换的事实标准。命令行工具 pandoc 可直接调用。

支持格式一览（pandoc 3.9.0）

类别	格式名	输入	输出	备注
Markdown系	`markdown`	✅	✅	全扩展默认开启
	`markdown_strict`	✅	✅	原始Markdown
	`markdown_phpextra`	✅	✅	PHP Markdown Extra
	`markdown_mmd`	✅	✅	MultiMarkdown
	`markdown_github`	✅	✅	GitHub 旧版
	`gfm`	✅	✅	GitHub Flavored Markdown
	`commonmark`	✅	✅	CommonMark 标准
	`commonmark_x`	✅	✅	CommonMark + 扩展
	`markua`	—	✅	Markua (Leanpub)
HTML系	`html`	✅	✅	自动检测版本
	`html4`	—	✅	HTML 4.01
	`html5`	—	✅	HTML 5
	`chunkedhtml`	—	✅	分块HTML（多文件）
办公文档	`docx`	✅	✅	Word (.docx)
	`odt`	✅	✅	LibreOffice (.odt)
	`pptx`	✅	✅	PowerPoint
	`xlsx`	✅	—	Excel (输入)
	`csv`	✅	—	CSV (输入)
	`tsv`	✅	—	TSV (输入)
	`rtf`	✅	✅	Rich Text Format
	`opendocument`	—	✅	ODF 开放文档
电子书	`epub`	✅	✅	EPUB 3
	`epub2`	—	✅	EPUB 2
	`epub3`	—	✅	EPUB 3 严格模式
	`fb2`	✅	✅	FictionBook 2
LaTeX系	`latex`	✅	✅	LaTeX
	`beamer`	—	✅	Beamer 幻灯片
	`context`	—	✅	ConTeXt
学术出版	`bibtex`	✅	✅	BibTeX
	`biblatex`	✅	✅	BibLaTeX
	`csljson`	✅	✅	CSL JSON
	`ris`	✅	—	RIS (输入)
	`endnotexml`	✅	—	Endnote XML (输入)
	`jats`	✅	✅	JATS XML
	`jats_archiving`	—	✅	JATS 存档版
	`jats_articleauthoring`	—	✅	JATS 作者版
	`jats_publishing`	—	✅	JATS 出版版
	`bits`	✅	—	BITS (输入)
轻量标记	`asciidoc`	✅	✅	AsciiDoc
	`asciidoc_legacy`	—	✅	AsciiDoc 旧版
	`asciidoctor`	—	✅	Asciidoctor 风味
	`rst`	✅	✅	reStructuredText
	`org`	✅	✅	Emacs Org mode
	`textile`	✅	✅	Textile
	`creole`	✅	—	Creole (输入)
	`haddock`	✅	✅	Haddock
	`djot`	✅	✅	Djot
	`muse`	✅	✅	Muse
	`t2t`	✅	—	txt2tags (输入)
Wiki系	`mediawiki`	✅	—	MediaWiki (输入)
	`dokuwiki`	✅	✅	DokuWiki
	`vimwiki`	✅	—	Vimwiki (输入)
	`tikiwiki`	✅	—	TikiWiki (输入)
	`twiki`	✅	—	TWiki (输入)
	`xwiki`	—	✅	XWiki
	`zimwiki`	—	✅	Zim Wiki
	`jira`	✅	—	Jira (输入)
	`pod`	✅	—	Perl POD (输入)
幻灯片	`revealjs`	—	✅	reveal.js
	`slidy`	—	✅	Slidy
	`slideous`	—	✅	Slideous
	`s5`	—	✅	S5
	`dzslides`	—	✅	DZSlides
文本终端	`plain`	—	✅	纯文本
	`ansi`	—	✅	终端ANSI彩色
	`man`	✅	✅	groff man
	`mdoc`	✅	—	mdoc (输入)
	`ms`	—	✅	groff ms
编程/数据	`json`	✅	✅	Pandoc AST
	`native`	✅	✅	Haskell AST
	`ipynb`	✅	✅	Jupyter Notebook
	`xml`	✅	✅	Pandoc XML
PDF	`pdf`	—	✅	需配置 PDF引擎
其他	`typst`	✅	✅	Typst
	`docbook`	✅	✅	DocBook
	`docbook4`	—	✅	DocBook 4
	`docbook5`	—	✅	DocBook 5
	`opml`	✅	✅	OPML
	`tei`	—	✅	TEI
	`texinfo`	—	✅	Texinfo
	`icml`	—	✅	InDesign (ICML)
	`bbcode`	—	✅	BBCode (通用)
	`bbcode_fluxbb`	—	✅	FluxBB
	`bbcode_hubzilla`	—	✅	Hubzilla
	`bbcode_phpbb`	—	✅	phpBB
	`bbcode_steam`	—	✅	Steam
	`bbcode_xenforo`	—	✅	XenForo
	`vimdoc`	—	✅	Vim help
自定义	`custom`	—	✅	Lua writer
	Lua reader	✅(自定义)	—	Lua reader路径

安装

# Windows: 下载 msi 安装包或
choco install pandoc
# 验证
pandoc --version

基本语法

pandoc [选项] [输入文件]...

无输入文件 → 从 stdin 读取
默认输出 → stdout
默认输入格式 → 自动检测（从扩展名或内容启发式判断）
默认输出 → 文档片段（非完整HTML/LaTeX），加 -s 生成独立文档

二、核心选项速查

输入/输出

选项	说明
`-f FORMAT, --from=FORMAT`	输入格式；可加扩展如 `markdown+emoji`
`-t FORMAT, --to=FORMAT`	输出格式；可加减扩展
`-o FILE, --output=FILE`	输出文件
`-s, --standalone`	生成完整独立文档（含 head/body 模板）
`--toc, --table-of-contents`	自动生成目录
`--toc-depth=NUMBER`	目录深度，默认 3

元数据控制

选项	说明
`-M KEY[=VAL], --metadata=KEY[:VAL]`	设置元数据字段
`--metadata-file=FILE`	从 YAML/JSON 文件读取元数据
`-V KEY=VAL, --variable=KEY:VAL`	设置模板变量
`--template=FILE`	指定模板文件/名称

过滤与处理

选项	说明
`-F, --filter=PROGRAM`	应用过滤器(JSON)
`-L, --lua-filter=SCRIPT`	应用Lua过滤器
`--citeproc`	处理引用(需CSL库)
`--highlight-style=STYLE`	代码高亮样式(pygments/kate/monochrome等)
`--no-highlight`	禁用代码高亮

PDF 相关

选项	说明
`--pdf-engine=PROGRAM`	指定PDF引擎(pdflatex/lualatex/xelatex/wkhtmltopdf/weasyprint等)
`-C, --css=CSS`	HTML中间格式时使用的CSS(可多个)
`--dpi=NUMBER`	图片DPI，默认 96(HTML)/144(LaTeX)

其他常用

选项	说明
`--extract-media=DIR`	提取所有媒体文件到目录
`--resource-path=DIR`	资源搜索路径
`--eol=crlf\\|lf\\|native`	换行符风格
`--tab-stop=NUMBER`	Tab宽度，默认4
`--defaults=FILE, -d FILE`	使用YAML/JSON默认配置文件
`--verbose`	详细日志
`--quiet`	静默模式
`--fail-if-warnings`	警告即失败
`--sandbox`	沙盒模式(禁文件系统访问)

三、输入/输出格式全集

输入格式 (`-f`)

类别	格式名
Markdown系	`markdown`(默认启用所有扩展), `commonmark`, `commonmark_x`, `gfm`, `markdown_phpextra`, `markdown_strict`, `markdown_mmd`(MultiMarkdown)
轻量标记	`asciidoc`, `creole`, `djot`, `org`, `pod`, `rst`, `textile`, `tikiwiki`, `twiki`, `vimwiki`, `muse`, `t2t`
HTML系	`html`, `html4`, `html5`
办公文档	`docx`(Word), `odt`, `pptx`, `xlsx`, `csv`, `tsv`
学术	`bibtex`, `biblatex`, `csljson`, `ris`
电子书	`epub`, `fb2`, `fictionbook2`
LaTeX系	`latex`, `beamer`, `context`
其他	`json`(AST), `typst`, `man`, `docbook`, `jats`(bits), `ipynb`(Jupyter), `opml`, `endnotexml`
自定义	自定义Lua reader路径

输出格式 (`-t`)

类别	格式名
Markdown系	同上全部
HTML系	`html`, `html4`, `html5`
幻灯片	`beamer`, `pptx`, `revealjs`, `slidy`, `slideous`, `dzslides`, `s5`
办公文档	`docx`, `odt`, `pptx`, `xlsx`, `rtf`
电子书	`epub`, `epub2`, `epub3`
LaTeX系	`latex`, `context`
PDF	`pdf`(需PDF引擎)
学术	`bibtex`, `biblatex`, `csljson`, `ris`
文本	`plain`, `ansi`(终端彩色)
其他	`typst`, `man`, `ms`(groff), `texinfo`, `docbook`, `jats`, `opml`, `tei`, `json`(AST), `ipynb`, `inDesign(icml)`, `chunkedhtml`, `asciidoc`, `asciidoc_legacy`, `custom`(Lua writer)

四、展机制

通过 +EXTENSION 或 -EXTENSION 在格式名后加减扩展：

pandoc -f markdown+emoji-hard_line_breaks -t html
pandoc -f markdown-auto_identifiers+gfm_auto_identifiers

关键扩展速查（Markdown）

缩写	扩展名	说明
标记	`mark`	高亮标记 ==text==
表情	`emoji`	:smile: → 😄
硬换行	`hard_line_breaks`	换行即断行
行内笔记	`inline_notes`	行内脚注
引用	`citations`	@citekey 引用
定义列表	`definition_lists`	术语定义
数学	`tex_math_dollars`	$...$ 行内, $$...$$ 块级
数学(带转义)	`tex_math_single_backslash`	(公式行内)，[公式块]
表格	`pipe_tables`, `grid_tables`, `multiline_tables`, `simple_tables`	各种表格语法
代码块属性	`fenced_code_attributes`	```{=html} 等
围栏代码块	`fenced_code_blocks`	``` 代码块语法
元数据块	`yaml_metadata_block`	YAML front matter
自动标识	`auto_identifiers` / `gfm_auto_identifiers`	标题自动ID
上标下标	`superscript`, `subscript`	^上标^, ~下标~
脚注	`footnotes`	[^1] 脚注
换行空格	`escaped_line_breaks`	行尾反斜杠换行
括号span	`bracketed_spans`	[文本]{属性}
围栏div	`fenced_divs`	::: 语法
原生div/spans	`native_divs`, `native_spans`	原生HTML div/span
原始属性	`raw_attribute`	```{=format}
隐式header引用	`implicit_header_references`	[Heading text] 链接
链接属性	`link_attributes`	链接可加属性
任务列表	`task_lists`	- [x] 任务项
删除线	`strikeout`	删除
网格表格	`grid_tables`	网格表格语法
无标题表	`headerless_tables`	无表头表格
示例列表	`example_lists`	@label 编号列表
起始编号	`startnum`	列表起始编号
标题属性	`header_attributes`	标题加 `{#id .class key=val}`
缩写	`abbreviations`	缩写展开

常见组合

markdown = 几乎所有扩展全开
commonmark_x = CommonMark + 扩展
gfm = GitHub Flavored Markdown
markdown_strict = 原始 Markdown

五、Defaults 文件（YAML/JSON 配置）

最推荐的使用方式，将复杂选项保存在 YAML 文件中：

# pandoc-defaults.yaml
from: markdown+emoji
to: html5
standalone: true
toc: true
toc-depth: 3
highlight-style: tango
pdf-engine: xelatex
template: letter
variables:
  mainfont: "Noto Serif CJK SC"
  fontsize: 12pt
  colorlinks: true
metadata:
  author: "作者名"
  title: "文档标题"
  date: "2026-04-27"
filters:
  - citeproc
  - count-words.lua

使用：

pandoc -d pandoc-defaults.yaml input.md -o output.pdf

可放在 $USERDATA/defaults/ 目录下，用短名调用：pandoc -d mydefaults

环境变量插值（仅文件路径字段）：

csl: ${HOME}/style.csl
epub-cover-image: ${.}/cover.jpg  # ${.} = defaults文件所在目录
resource-path:
  - .
  - ${.}/images

六、模板系统

模板变量

pandoc -s --template=letter -V mainfont="Noto Serif" input.md

模板语法速查

语法	说明
$variable$	变量值
`$if(variable)$...$endif$`	条件块
`$if(variable)$...$else$...$endif$`	条件-否则
`$for(variable)$...$endfor$`	循环
$variable.subfield$	嵌套字段
$body$	文档主体
$toc$	目录
$title$ , $author$ , $date$	文档元数据
$highlighting-css$	代码高亮CSS

常用模板变量

变量	说明	适用格式
`fontsize`	字体大小(11pt/12pt)	LaTeX/PDF
`papersize`	纸张大小(a4/letter)	LaTeX/PDF
`documentclass`	文档类(article/report/book)	LaTeX/PDF
`mainfont`, `sansfont`, `monofont`	字体	XeLaTeX/PDF
`geometry`	页边距(margin=1in)	LaTeX/PDF
`colorlinks`	彩色链接(true/false)	LaTeX/PDF
`linkcolor`, `citecolor`, `urlcolor`	链接颜色	LaTeX/PDF
`CJKmainfont`	中日韩主字体	XeLaTeX
`lang`	文档语言	LaTeX/HTML
`title`, `author`, `date`	标题作者日期	所有
`css`	CSS文件路径	HTML
`header-includes`	额外header内容	HTML/LaTeX
`include-before`/`include-after`	正文前后内容	HTML/LaTeX

七、PDF 生成路径

方式1：直接生成（推荐）

pandoc input.md -o output.pdf --pdf-engine=xelatex

方式2：通过中间 LaTeX（调试用）

pandoc input.md -s -o output.tex     # 生成LaTeX
pdflatex output.tex                   # 手动编译为PDF

PDF引擎选项

引擎	说明
`pdflatex`	传统LaTeX（不直接支持Unicode）
`lualatex`	现代LaTeX，原生Unicode
`xelatex`	Unicode支持+系统字体，推荐中文
`wkhtmltopdf`	通过HTML/CSS渲染
`weasyprint`	Python HTML/CSS→PDF
`context`	ConTeXt排版引擎
`tectonic`	现代LaTeX引擎

中文PDF推荐配置

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V mainfont="SimSun" \
  -V sansfont="SimHei" \
  -V monofont="SimHei" \
  -V CJKmainfont="SimSun" \
  -V geometry:margin=1in \
  -V fontsize=12pt \
  -V documentclass=ctexart

八、Pandoc Markdown 增强特性

YAML 元数据块

---
title: "文档标题"
author: "作者"
date: "2026-04-27"
abstract: "摘要"
bibliography: refs.bib
csl: style.csl
toc: true
toc-depth: 3
---

表格

# 管道表格
| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 内容   | 内容 | 内容   |

# 网格表格
+-------+------+-------+
| 左    | 居中 | 右    |
+=======+======+=======+
| 内容  | 内容 | 内容  |
+-------+------+-------+

脚注

这是正文[^1]，更多内容[^longnote]。

[^1]: 简短脚注。
[^longnote]: 可以包含多个段落的脚注。

引用

@smith2019 证明...
详见 [@smith2019, pp. 33-35]

数学

行内公式: $E = mc^2$
块级公式:
$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

代码块

```python
def hello():
    print("Hello, world!")

### 列表
```markdown
1.  有序列表
    i) 子列表用不同标识符
    ii) 缩进对齐即可
2.  继续主列表

- 无序列表
- 任务列表:
  - [x] 已完成
  - [ ] 未完成

其他增强

H~2~O是下标，x^2^是上标
~~删除线~~
==高亮标记==
[链接文本](url "标题"){#id .class key=val}
![图片](path){width=50%}

九、实用配方

1. Markdown → Word

pandoc input.md -o output.docx --toc --reference-doc=template.docx

2. Markdown → PDF（中文）

pandoc input.md -o output.pdf --pdf-engine=xelatex -V CJKmainfont=SimSun

3. Markdown → HTML 幻灯片

pandoc input.md -t revealjs -s -o slides.html --slide-level=2 -V theme=beige

4. Word → Markdown

pandoc input.docx -t markdown --wrap=none --extract-media=./media -o output.md

5. Markdown → EPUB

pandoc input.md -o output.epub --toc --metadata title="书名" --metadata author="作者"

6. HTML → Markdown

pandoc https://example.com -f html -t markdown -o output.md

7. LaTeX → Word

pandoc input.tex -o output.docx --bibliography=refs.bib

8. 多文件合并转换

pandoc ch1.md ch2.md ch3.md -s -o book.pdf --pdf-engine=xelatex

9. 指定代码高亮

pandoc input.md -o output.html -s --highlight-style=tango

10. 批量转换（PowerShell）

Get-ChildItem *.md | ForEach-Object {
    pandoc $_.Name -o "$($_.BaseName).docx"
}

十、常用错误码

码	含义	常见原因
1	PandocIOError	文件不存在/权限问题
3	FailOnWarningError	启用了--fail-if-warnings
4	PandocAppError	应用级错误
5	PandocTemplateError	模板语法/变量错误
6	PandocOptionError	选项不合法
21	UnknownReaderError	输入格式未知
22	UnknownWriterError	输出格式未知
23	UnsupportedExtensionError	扩展不支持
31	EpubSubdirectoryError	EPUB子目录错误
66	MakePDFError	PDF生成失败
83	FilterError	过滤器错误
84	LuaError	Lua脚本错误
92	UTF8DecodingError	UTF-8解码错误

十一、避坑指南

编码问题：始终用 UTF-8 编码；Windows 下 chcp 65001 再执行
PDF中文：必须用 xelatex/lualatex，pdflatex 不支持 Unicode
图片路径：相对路径相对于源文件所在目录
独立文档：需要完整 <head>/<body> 时必须加 -s
Tab问题：pandoc 默认将 tab 转换为空格，代码块需 --preserve-tabs
引用处理：需要 --citeproc + bibliography 字段才能处理引用
模板优先级：-V 变量 > defaults 文件 > 元数据 YAML 块
扩展冲突：+smart -smart 会取消 smart 扩展
网络输入：可通过 HTTP URL 作为输入，但需注意请求头限制
文件监控：pandoc 无内置 watch 模式，需配合 entr/fswatch

十二、行动策略

收到文档转换任务时

确认格式：输入文件格式、期望输出格式
确认需求：是否需要独立文档(-s)、目录(--toc)、PDF引擎指定
构建命令：优先使用 defaults YAML 文件（便于复用）
先试后调：先执行基础转换，再叠加样式/模板/过滤
错误排查：

检查 pandoc 是否安装：pandoc --version
检查输入文件编码和路径
生成中间格式调试：不用 -o output.pdf，用 -s -o output.tex
逐步移除扩展和过滤器定位问题

无 pandoc 时

choco install pandoc
# 或手动下载: https://pandoc.org/installing.html

探索未知功能

pandoc --list-input-formats   # 列出所有输入格式
pandoc --list-output-formats  # 列出所有输出格式
pandoc --list-extensions=markdown  # 列出markdown扩展
pandoc --list-highlight-styles     # 代码高亮样式
pandoc --list-highlight-languages  # 支持的语言