# 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路径 |

### 安装

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

### 基本语法

```bash
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` 在格式名后加减扩展：

```bash
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 文件中：

```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
```

使用：

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

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

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

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

## 六、模板系统

### 模板变量

```bash
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：直接生成（推荐）

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

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

```bash
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推荐配置

```bash
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 元数据块

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

### 表格

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

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

### 脚注

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

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

### 引用

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

### 数学

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

### 代码块

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

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

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

### 其他增强

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

## 九、实用配方

### 1. Markdown → Word

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

### 2. Markdown → PDF（中文）

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

### 3. Markdown → HTML 幻灯片

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

### 4. Word → Markdown

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

### 5. Markdown → EPUB

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

### 6. HTML → Markdown

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

### 7. LaTeX → Word

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

### 8. 多文件合并转换

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

### 9. 指定代码高亮

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

### 10. 批量转换（PowerShell）

```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解码错误 |

## 十一、避坑指南

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

## 十二、行动策略

### 收到文档转换任务时

1. **确认格式**：输入文件格式、期望输出格式
2. **确认需求**：是否需要独立文档(`-s`)、目录(`--toc`)、PDF引擎指定
3. **构建命令**：优先使用 defaults YAML 文件（便于复用）
4. **先试后调**：先执行基础转换，再叠加样式/模板/过滤
5. **错误排查**：
  - 检查 pandoc 是否安装：`pandoc --version`
  - 检查输入文件编码和路径
  - 生成中间格式调试：不用 `-o output.pdf`，用 `-s -o output.tex`
  - 逐步移除扩展和过滤器定位问题

### 无 pandoc 时

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

### 探索未知功能

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