Pandoc 文档格式转换工具完整指南

从入门到精通的文档格式转换瑞士军刀

学习主题：Pandoc 文档转换工具

适用人群：Markdown 用户、技术文档作者、学术写作者、出版从业者

学习目标：掌握 Pandoc 的安装、基本命令、格式转换、模板定制和高级技巧

一、Pandoc 简介

Pandoc 是由 John MacFarlane 开发的开源文档格式转换工具，被誉为"文档转换界的瑞士军刀"。它可以在数十种文档格式之间进行双向转换，是技术写作、学术出版和文档自动化领域不可或缺的工具。Pandoc 的名称来源于希腊语"πᾶν"（所有）和"doc"（文档），意为"所有文档"，精准地概括了它的核心能力。

Pandoc 最初是为学术写作而设计的——John MacFarlane 本人是加州大学伯克利分校的哲学教授，他需要一种能将 Markdown 转换为 LaTeX 再生成 PDF 的工具。这解释了为什么 Pandoc 对学术写作有如此出色的支持，包括引文管理、交叉引用、LaTeX 数学公式等。

核心特点：免费开源、跨平台（Windows/Mac/Linux）、支持数十种输入输出格式、高度可定制（模板、过滤器）、活跃的社区生态。

1.1 支持的格式

Pandoc 支持极其丰富的文档格式转换。作为 输入格式，它可以读取 Markdown（含多种变体）、ReStructuredText、HTML、LaTeX、DocBook、JATS、OPML、Org-mode、Emacs Org、EPUB、Textile、CSV 等多种格式。作为 输出格式，它可以生成 HTML（含 HTML5）、PDF（通过 LaTeX 或 wkhtmltopdf）、Word（docx）、OpenDocument（odt）、EPUB（epub2/epub3）、LaTeX、ConTeXt、DocBook、JATS、Markdown（含多种变体）、ReStructuredText、AsciiDoc、ICML、TEI、man page、roff、MediaWiki、DokuWiki、ZimWiki、Jira Wiki、Showdown、RTF、OPML、Org-mode、S5/ Slideous/ Slidy/ DZSlides 幻灯片、reveal.js 幻灯片、PDF 演示文稿（通过 beamer）等多种格式。

类别输入格式输出格式
标记语言Markdown, HTML, ReStructuredTextMarkdown, HTML, ReStructuredText, AsciiDoc
办公文档CSVWord (docx), OpenDocument (odt), RTF
学术出版LaTeX, DocBook, JATSLaTeX, PDF, EPUB, DocBook, JATS
电子书EPUBEPUB (v2/v3), PDF
演示文稿—reveal.js, beamer, Slideous 等
Wiki 标记MediaWiki, DokuWikiMediaWiki, DokuWiki, Jira Wiki

1.2 安装方法

Pandoc 的安装非常简单，支持多种操作系统和包管理器。下面列出各平台的推荐安装方式。

Windows

# 方式一：从官网下载安装包 https://pandoc.org/installing.html # 方式二：使用 winget winget install Pandoc # 方式三：使用 Chocolatey choco install pandoc # 方式四：使用 Scoop scoop install pandoc

macOS

# 方式一：使用 Homebrew（推荐） brew install pandoc # 方式二：使用 MacPorts sudo port install pandoc

Linux

# Ubuntu/Debian sudo apt-get install pandoc # CentOS/RHEL/Fedora sudo yum install pandoc # Arch Linux sudo pacman -S pandoc

安装完成后，打开终端输入 pandoc --version 可以验证安装是否成功。如果你需要生成 PDF，还需要额外安装 LaTeX 发行版。在 Windows 上推荐安装 MiKTeX，在 macOS 上推荐 MacTeX（或 BasicTeX 精简版），在 Linux 上推荐 texlive。

二、基本用法

2.1 最简单的转换

Pandoc 的基本命令格式非常简单：pandoc [输入文件] -o [输出文件]。Pandoc 会根据文件扩展名自动判断格式，所以大多数情况下你不需要显式指定格式参数。

# Markdown 转换为 HTML pandoc input.md -o output.html # Markdown 转换为 Word 文档 pandoc input.md -o output.docx # Markdown 转换为 PDF pandoc input.md -o output.pdf # HTML 转换为 Markdown pandoc input.html -o output.md

提示：pandoc --help 可以查看所有可用选项的简要说明，pandoc --version 查看版本和编译信息。

2.2 指定输入输出格式

如果需要覆盖自动格式检测，或者处理标准输入/输出，可以使用 -f（from）和 -t（to）参数显式指定格式。

# 显式指定格式 pandoc -f markdown -t html input.md -o output.html # 从标准输入读取，输出到标准输出 cat input.md | pandoc -f markdown -t html -o output.html # 输出到标准输出（查看转换结果） pandoc input.md -t html
# 常用的格式名称 -f markdown # Markdown（Pandoc 扩展版本） -f markdown_strict # 严格 Markdown（无扩展） -f gfm # GitHub Flavored Markdown -f markdown+smart # 启用 smart 扩展（智能引号等） -t html5 # HTML5 -t pdf # PDF -t docx # Word -t latex # LaTeX -t epub3 # EPUB 3 -t revealjs # reveal.js 幻灯片 -t beamer # LaTeX beamer 演示文稿

2.3 多文件合并

Pandoc 可以同时处理多个输入文件，并将它们合并为单个输出文件。这在撰写长篇文档（如书籍、论文）时非常有用。

# 合并多个 Markdown 文件 pandoc chapter1.md chapter2.md chapter3.md -o book.html # 合并并生成 Word 文档 pandoc intro.md chapter1.md chapter2.md conclusion.md -o book.docx # 使用通配符 pandoc chapters/*.md -o book.html

注意：合并时，Pandoc 会在每个文件之间插入水平线，除非你使用 --file-scope 选项让每个文件独立处理后再连接。合并长文档时，建议使用 YAML 元数据块来统一管理文档标题、作者等元信息。

三、核心功能详解

3.1 YAML 元数据块

Pandoc 支持在 Markdown 文档的顶部使用 YAML 元数据块（也称为 front matter）来定义文档的元信息。元数据块以 --- 开头和结尾，支持标题、作者、日期、目录设置等多种字段。

--- title: "Pandoc 使用指南" author: - 张三 - 李四 date: "2026-05-07" abstract: "本文全面介绍 Pandoc 文档转换工具的使用方法..." lang: zh-CN toc: true toc-depth: 3 numbersections: true --- # 正文开始 这里写文档的正文内容...

YAML 元数据块中的字段可以被 Pandoc 的输出模板引用。例如，title 会自动出现在生成的 HTML 标题和页面标题中，toc: true 会自动生成目录。不同的输出格式对这些元数据的支持程度不同，但大部分通用的元数据字段都能被正确渲染。

3.2 目录生成

使用 --toc（或 --table-of-contents）选项可以自动生成目录。结合 --toc-depth 可以控制目录的标题层级深度。

# 生成包含目录的 HTML pandoc input.md --toc --toc-depth=3 -o output.html # 生成包含目录的 Word 文档 pandoc input.md --toc -o output.docx # 在 YAML 元数据中控制 # --- # title: "我的文档" # toc: true # toc-depth: 2 # ---

3.3 自定义模板

Pandoc 使用模板系统来控制输出文档的最终外观。模板是包含占位变量的文档骨架，Pandoc 会在渲染时用实际内容替换这些变量。你可以使用 --template 参数指定自定义模板，也可以使用 -D 参数查看默认模板内容。

# 查看默认 HTML 模板 pandoc -D html # 使用自定义模板 pandoc input.md --template=my-template.html -o output.html # 保存默认模板并修改 pandoc -D html > my-template.html # 编辑 my-template.html 然后使用： pandoc input.md --template=my-template.html -o output.html

自定义模板是 Pandoc 最强大的功能之一。在 HTML 模板中，你可以完全控制页面布局、CSS 样式、JavaScript 交互等。模板语法使用 $变量名$ 的形式引用变量，如 $title$、$body$、$toc$ 等。你还可以使用条件判断和循环来构建复杂的模板逻辑。

<!-- 自定义模板片段示例 --> <!DOCTYPE html> <html> <head> <title>$title$</title> $if(css)$ <link rel="stylesheet" href="$css$"> $endif$ </head> <body> $if(toc)$ <nav>$toc$</nav> $endif$ $body$ </body> </html>
模板语法说明：

$title$ — 文档标题

$body$ — 文档正文

$toc$ — 目录

$if(变量)$...$endif$ — 条件判断

$for(变量)$...$endfor$ — 循环

3.4 CSS 样式定制

生成 HTML 时，你可以通过 --css 参数指定一个或多个 CSS 样式文件，控制输出 HTML 的外观。

# 应用自定义 CSS pandoc input.md --css=style.css -o output.html # 应用多个 CSS 文件 pandoc input.md --css=reset.css --css=style.css -o output.html # 在 YAML 元数据中指定 CSS # --- # title: "我的文档" # css: style.css # ---

3.5 代码块高亮

Pandoc 内置了代码语法高亮功能，支持多种高亮风格。使用 --highlight-style 参数可以选择不同的主题。

# 查看可用的高亮风格 pandoc --list-highlight-styles # 使用特定高亮风格 pandoc input.md --highlight-style=pygments -o output.html pandoc input.md --highlight-style=tango -o output.html pandoc input.md --highlight-style=monochrome -o output.html pandoc input.md --highlight-style=breezedark -o output.html # 导出自定义高亮风格 pandoc --print-highlight-style=pygments > my-theme.style # 然后使用自定义风格 pandoc input.md --highlight-style=my-theme.style -o output.html

高亮风格推荐：pygments（默认，清晰易读）、tango（暖色调）、breezedark（深色主题，适合暗色背景页面）。

四、格式转换实战

4.1 Markdown 转 HTML

这是最常用的转换场景。Pandoc 提供了比基础 Markdown 渲染器更丰富的 HTML 输出控制。

# 基础转换 pandoc article.md -o article.html # 带样式和目录 pandoc article.md --toc --css=github.css -o article.html # 独立 HTML（包含 <html> 骨架） pandoc article.md -s -o article.html # 自定义标题 pandoc article.md -s --metadata title="我的文章" -o article.html # 添加数学公式支持（使用 MathJax） pandoc article.md --mathjax -o article.html

-s（或 --standalone）参数非常关键：不加 -s 时，Pandoc 只输出 HTML 片段（不含 <html>、<head> 等骨架标签）；加上 -s 后，输出完整的独立 HTML 页面。

4.2 Markdown 转 Word

Pandoc 可以生成格式良好的 Word 文档，这在技术文档写作中非常实用。你可以通过 --reference-doc 参数使用自定义的 Word 模板来控制输出样式。

# 基本转换 pandoc report.md -o report.docx # 使用参考模板控制样式 pandoc report.md --reference-doc=template.docx -o report.docx # 生成带目录的 Word 文档 pandoc report.md --toc -o report.docx # 使用自定义元数据 pandoc report.md --metadata title="季度报告" --metadata author="张三" -o report.docx

提示：要创建参考模板，先手动生成一个 Word 文档：pandoc -o template.docx，然后编辑该文档的样式（修改"标题1"、"正文"等样式），再用 --reference-doc=template.docx 应用到新的转换中。

4.3 Markdown 转 PDF

生成 PDF 需要安装 LaTeX 引擎（推荐 MiKTeX/TeX Live），Pandoc 默认使用 LaTeX 作为 PDF 生成引擎。也可以使用 --pdf-engine 指定其他引擎。

# 基本 PDF 转换（需要 LaTeX） pandoc article.md -o article.pdf # 使用 xelatex 引擎（更好的中文支持） pandoc article.md --pdf-engine=xelatex -o article.pdf # 使用 wkhtmltopdf（不需要 LaTeX） pandoc article.md --pdf-engine=wkhtmltopdf -o article.pdf # 自定义 PDF 选项 pandoc article.md --pdf-engine=xelatex \ -V mainfont="SimSun" \ -V margin-top=2cm \ -V margin-bottom=2cm \ -o article.pdf

中文 PDF 注意事项：生成中文 PDF 时推荐使用 xelatex 引擎，并通过 -V mainfont="SimSun" 指定中文字体。如果遇到字体问题，可以先在命令行执行 fc-list :lang=zh 查看已安装的中文字体。也可以使用 -V CJKmainfont="SimSun" 单独设置 CJK 字体。

4.4 Markdown 转 EPUB 电子书

Pandoc 可以生成标准 EPUB 电子书格式，支持封面、目录、元数据等完整的电子书特性。

# 基本 EPUB 转换 pandoc book.md -o book.epub # 指定元数据和封面 pandoc book.md --metadata title="我的书" \ --metadata author="作者名" \ --epub-cover-image=cover.jpg \ -o book.epub # EPUB 3（最新标准） pandoc book.md -t epub3 -o book.epub # 使用自定义 CSS pandoc book.md --css=epub.css -o book.epub

4.5 生成演示文稿

Pandoc 可以将 Markdown 直接转换为各种格式的演示文稿，包括 HTML 幻灯片和 PDF 演示文档。

# 生成 reveal.js 幻灯片 pandoc slides.md -t revealjs -o slides.html # 生成 beamer PDF 演示文稿 pandoc slides.md -t beamer -o slides.pdf # 生成 Slideous 幻灯片 pandoc slides.md -t slideous -o slides.html

Pandoc 的幻灯片语法基于 Markdown 的标题层级：一级标题 # 作为整个演示文稿的标题，二级标题 ## 作为每张幻灯片的标题，二级标题之间的内容构成一张幻灯片的内容。

# 演示文稿标题 ## 第一页 - 要点 1 - 要点 2 - 要点 3 ## 第二页 1. 步骤 1 2. 步骤 2 3. 步骤 3 ## 第三页 > 引用内容作为幻灯片的一部分

五、高级功能

5.1 过滤器（Filters）

过滤器是 Pandoc 最强大的扩展机制之一。过滤器本质上是一个程序，它读取 Pandoc 的内部 AST（抽象语法树），对其进行修改，然后输出修改后的 AST。通过过滤器，你可以实现自定义的文档转换逻辑。

Pandoc 过滤器可以用任何语言编写，最常用的是 Lua 脚本（Pandoc 内置 Lua 解释器，无需额外安装）和 Python（使用 pandocfilters 库）。

# 使用内置的 Lua 过滤器 pandoc input.md --lua-filter=my-filter.lua -o output.html # 使用外部过滤器（如 Python） pandoc input.md --filter=pandoc-citeproc -o output.html pandoc input.md --filter=my-filter.py -o output.html # 多个过滤器可以串联使用 pandoc input.md --lua-filter=filter1.lua --filter=filter2.py -o output.html

常见过滤器的应用场景包括：自动编号标题和图表、自定义代码块渲染、添加自定义警告框/提示框、处理特殊的标记语法、自动生成交叉引用和链接等。

5.2 引文管理

Pandoc 通过 pandoc-citeproc（内置版本）或 citeproc 过滤器支持完整的引文管理功能。你可以使用 BibTeX、CSL-JSON 等格式的文献库，配合 CSL（Citation Style Language）样式文件自动格式化引文和参考文献。

--- title: "学术论文" bibliography: references.bib csl: ieee.csl --- # 引言 如相关研究所示 [@smith2020]， 这一发现具有重要意义 [@doe2019, p. 42]。 See also @johnson2021 [chap. 3]。 ## 参考文献
# 使用引文生成 HTML pandoc paper.md --citeproc -o paper.html # 使用引文生成 Word pandoc paper.md --citeproc -o paper.docx # 使用引文生成 PDF pandoc paper.md --citeproc --pdf-engine=xelatex -o paper.pdf

5.3 交叉引用

通过 pandoc-crossref 过滤器，Pandoc 可以实现类似 LaTeX 的交叉引用功能，自动编号图表、公式、代码块并生成交叉引用链接。

# 安装 pandoc-crossref # 从 https://github.com/lierdakil/pandoc-crossref 下载对应平台的二进制文件 # Markdown 中使用交叉引用 请看 @fig:architecture 中的架构图。 ![系统架构图](architecture.png){#fig:architecture} 如 @tbl:comparison 所示。 | 特性 | Pandoc | 其他工具 | |------|--------|----------| | 格式支持 | 丰富 | 有限 | : 功能对比 {#tbl:comparison} 使用交叉引用： pandoc doc.md --filter=pandoc-crossref -o doc.html

5.4 数学公式

Pandoc 原生支持 LaTeX 数学公式语法，可以渲染为 HTML（使用 MathJax 或 KaTeX）或在 PDF 中完美渲染。

# Markdown 中的数学公式 行内公式：$E = mc^2$ 独立公式： $$ \int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi} $$ # 使用 MathJax 渲染为 HTML pandoc math.md --mathjax -o math.html # 使用 KaTeX（更快的渲染引擎） pandoc math.md -t html5 --katex -o math.html # PDF 中直接渲染（需要 LaTeX） pandoc math.md --pdf-engine=xelatex -o math.pdf

5.5 图表支持

Pandoc 可以通过过滤器将文本描述转换为图表。最常用的是结合 Mermaid 或 PlantUML，在文档中直接写图表定义，然后通过过滤器自动渲染为图片。

# 在 Markdown 中嵌入 Mermaid 图表 ```mermaid graph TD A[开始] --> B{判断} B -->|是| C[处理] B -->|否| D[结束] C --> D ``` # 使用 pandoc-mermaid-filter pandoc doc.md --filter=mermaid-filter -o doc.html

高级技巧总结：过滤器和模板是 Pandoc 生态中最有价值的两个扩展点。过滤器让你可以自定义文档转换逻辑（处理任意特殊的标记语法），模板让你可以控制输出文档的最终外观。学会使用这两者，你就真正掌握了 Pandoc 的精髓。

六、实战案例

6.1 撰写技术博客

# 用 Markdown 写博客，一键转换为 HTML + Word # 1. 生成 HTML（包含目录和代码高亮） pandoc blog-post.md --toc \ --highlight-style=tango \ --css=blog.css \ -s -o blog-post.html # 2. 同时生成 Word 版本 pandoc blog-post.md -o blog-post.docx # 3. 生成 PDF 版本 pandoc blog-post.md --pdf-engine=xelatex \ -V mainfont="SimSun" \ -o blog-post.pdf

6.2 批量转换脚本

# Windows PowerShell 批量转换 Get-ChildItem *.md | ForEach-Object { pandoc $_.Name -o "$($_.BaseName).html" -s --toc } # Linux/macOS 批量转换 for f in *.md; do pandoc "$f" -o "${f%.md}.html" -s --toc done # 批量转换为 Word for f in *.md; do pandoc "$f" -o "${f%.md}.docx" done

6.3 书籍排版

Pandoc 非常适合书籍排版工作流。你可以将每一章写成一个独立的 Markdown 文件，然后用 Pandoc 合并并生成完整的书籍文档。

--- title: "Python 编程入门" author: "张三" date: "2026-05-07" toc: true toc-depth: 3 numbersections: true --- # 第一章：Python 基础 # 第二章：数据类型 # 第三章：控制流 # 第四章：函数 合并命令： pandoc metadata.yaml ch1.md ch2.md ch3.md ch4.md \ --toc --number-sections \ --pdf-engine=xelatex \ -V mainfont="SimSun" \ -o book.pdf # 同时生成电子书 pandoc metadata.yaml ch1.md ch2.md ch3.md ch4.md \ --toc \ --epub-cover-image=cover.jpg \ -o book.epub

6.4 学术论文写作

Pandoc 的学术写作工作流可以完全替代传统的 LaTeX 写作方式，同时保留 Markdown 的简洁性。

--- title: "基于深度学习的图像识别研究" author: "李四" date: "2026-05-07" abstract: "本文研究了深度学习在图像识别领域的应用..." bibliography: references.bib csl: ieee.csl --- # 引言 深度学习在图像识别领域取得了显著成就 [@goodfellow2016]。 # 方法 # 实验 # 结论 # 参考文献 转换命令： pandoc paper.md --citeproc --bibliography=references.bib \ --pdf-engine=xelatex \ -V mainfont="SimSun" \ -o paper.pdf

核心要点总结

一、Pandoc 是文档格式转换的瑞士军刀，支持数十种格式的双向转换。

二、基本命令 pandoc input.md -o output.html 即可完成转换，Pandoc 自动根据扩展名判断格式。

三、YAML 元数据块用于管理文档的标题、作者、目录等元信息。

四、自定义模板是 Pandoc 最强大的功能，可以完全控制输出文档的外观。

五、生成中文 PDF 需使用 xelatex 引擎并配置中文字体。

六、过滤器和引文管理使 Pandoc 成为学术写作的理想工具。

七、批量转换脚本可以极大提高文档处理效率，适合自动化工流。

八、Pandoc + Markdown = 现代技术文档写作的最佳实践组合。

学习路径建议

第一步：安装 Pandoc 并用简单的 Markdown 文件练习基本转换（HTML、Word、PDF）。第二步：学习 YAML 元数据块和目录生成，控制文档结构。第三步：探索自定义模板和 CSS 样式，输出美观的 HTML 文档。第四步：学习过滤器（尤其是 Lua 过滤器），实现自动化文档处理。第五步：将 Pandoc 集成到你的文档工作流中，实现批量转换和持续集成。记住，Pandoc 的学习曲线是渐进的——每次学习一个新功能，逐步构建你的文档处理能力。