討論 – 开源软件研究

Pandoc：地表最强的开源文档格式转换工具

2026 年 2 月 4 日下午 4:00 #32997

在文档转换与自动化写作的领域，Pandoc 被公认为地表最强的格式转换工具。它是一个开源的命令行程序，能够将文档从一种标记格式完美地”翻译”成另一种格式。Pandoc 由加州大学伯克利分校的哲学教授 John MacFarlane 创建，使用函数式编程语言 Haskell 编写，自 2006 年首次发布以来，已成为学术界和技术写作领域的事实标准。

无论你是需要将 Markdown 转换为 Word，还是将 HTML 转为 PDF，通过 Pandoc 官网，你都能找到最高效的解决方案。

Pandoc 的核心优势

📚 支持格式极其广泛

Pandoc 支持超过 40 种输入格式和 60 种输出格式。它不仅能处理常见的 Markdown、HTML、Docx，还能胜任 LaTeX、EPUB、Org-mode 甚至 Jupyter Notebook (.ipynb) 文件。

以下是 Pandoc 支持的主要格式分类：

格式类别	具体格式示例
轻量级标记语言	Markdown（含 CommonMark、GitHub Flavored Markdown）、reStructuredText、AsciiDoc、Org-mode、Textile、djot、txt2tags
Wiki 标记语言	MediaWiki、DokuWiki、TikiWiki、TWiki、Vimwiki、XWiki、ZimWiki、Jira wiki、Creole
演示文稿格式	LaTeX Beamer、Microsoft PowerPoint (.pptx)、reveal.js、Slidy、S5、DZSlides
数据格式	CSV/TSV 表格、Excel 电子表格 (.xlsx)
电子书格式	EPUB、Kindle (MOBI/AZW3)
文档格式	Microsoft Word (.docx)、OpenDocument (.odt)、RTF
排版系统	LaTeX、ConTeXt、Typst

💡 版本更新提示：截至 2025 年 12 月发布的 Pandoc 3.8.3 版本，新增了三种输入格式（AsciiDoc 原生读取器、PowerPoint .pptx、Excel .xlsx）以及 BBCode 输出格式（支持 FluxBB、PhpBB、Hubzilla、Xenforo 等多种变体）。这意味着你现在可以直接读取 PowerPoint 演示文稿和 Excel 电子表格，并将其转换为任何其他支持的格式。

如何查看你系统上 Pandoc 支持的完整格式列表？

# 查看所有支持的输入格式
pandoc --list-input-formats

# 查看所有支持的输出格式
pandoc --list-output-formats

🎓 学术写作的神器

Pandoc 对数学公式（MathJax/LaTeX）和参考文献引用有原生支持。配合 Zotero 等文献管理工具，它是许多博士和研究人员撰写论文的首选。

Pandoc 的学术写作能力体现在以下几个方面：

✏️ 数学公式的完美呈现

Pandoc 能够在多种格式之间无缝转换数学公式，支持：

TeX/LaTeX 语法：学术界最广泛使用的数学排版语言
MathML：XML 标准数学标记语言
Word 公式：Microsoft Office 内置公式编辑器
roff eqn：Unix 传统排版系统
Typst：新一代排版系统的数学语法
纯文本 Unicode：适用于简单场景的 ASCII 表示

📖 强大的引用与文献管理系统

Pandoc 内置了一套基于 Citation Style Language (CSL) 的引文处理系统，能够自动生成符合各种学术规范的参考文献列表。

支持的文献数据格式包括：

BibTeX / BibLaTeX（LaTeX 传统格式）
CSL JSON / CSL YAML（推荐使用，是新兴的标准格式）
RIS（Research Information Systems 格式）
EndNote XML

与 Zotero 配合的推荐工作流：

┌─────────────┐    自动导出     ┌──────────────┐    编译     ┌─────────────┐
│   Zotero    │ ──────────────→ │  .bib/.json  │ ─────────→ │   Pandoc    │
│ (文献管理)   │  Better BibTeX │  (文献数据)   │            │   (转换)    │
└─────────────┘                 └──────────────┘            └──────┬──────┘
                                                                   │
                                      ┌─────────────────────────────┴─────────────────────────────┐
                                      ↓                             ↓                             ↓
                               ┌─────────────┐              ┌─────────────┐              ┌─────────────┐
                               │  .docx 论文  │              │  .pdf 论文   │              │ .html 网页  │
                               └─────────────┘              └─────────────┘              └─────────────┘

实践建议：

安装 Better BibTeX 插件：这是 Zotero 的一个重要扩展，可以从 Better BibTeX 官网下载。它能够实现文献库的自动同步导出，并提供更好的引用键（citation key）管理。
优先使用 CSL JSON 格式：相比 BibTeX，CSL JSON 是一种更现代的标准格式，避免了 BibTeX 在处理非英语字符、特殊符号时可能出现的编码问题。正如 R Markdown 作者谢益辉所推荐的，CSL-JSON 是一种值得采用的新兴标准。
配置引用样式：Pandoc 默认使用芝加哥手册（Chicago Manual of Style）的作者-日期格式。你可以通过 --csl 选项指定其他样式：

pandoc paper.md -o paper.docx --citeproc --bibliography=refs.json --csl=apa-7th-edition.csl

📌 获取 CSL 样式文件：访问 Zotero Style Repository 可下载超过 10,000 种期刊和出版机构的引用样式。

⚙️ 高度可定制化

通过使用”模板”（Templates）和”过滤器”（Filters，如 Lua filters），用户可以精确控制输出文档的样式、字体和排版布局。

🎨 模板系统（Templates）

**Pandoc 的模板系统允许你完全控制输出文档的结构和外观。**模板是包含 Pandoc 变量的文件，Pandoc 在转换时会用实际值替换这些变量。

不同输出格式使用不同的模板：

docx 输出：使用 --reference-doc 指定参考文档来调整样式
pdf 输出：使用 default.latex 模板（或 default.context、default.typst 等，取决于所选引擎）
html 输出：使用 default.html 模板

常用模板变量示例：

---
title: "我的论文标题"
author: "作者姓名"
date: "2026年1月"
fontsize: 12pt
geometry: margin=1in
linestretch: 1.5
---

推荐的第三方模板：

模板名称	适用场景	特点
Eisvogel	LaTeX/PDF 输出	专为学术讲义和练习设计，支持代码高亮、目录、页眉页脚等，兼容 Pandoc 3.x
Academic Pandoc Template	学术文章、演示文稿、论文	提供完整的学术写作工作流支持
kjhealy/pandoc-templates	HTML、LaTeX、PDF	社会科学学者常用的模板集合

🔧 Lua 过滤器系统

**从 Pandoc 2.0 版本开始，Lua 过滤器成为扩展 Pandoc 功能的首选方式。**Pandoc 内置了 Lua 5.4 解释器，无需安装任何外部依赖即可使用。

Lua 过滤器的工作原理：

当 Pandoc 读取文档时，会将内容解析为一个”抽象语法树”（Abstract Syntax Tree, AST）。Lua 过滤器允许你在转换过程中修改这个 AST，从而实现各种高级定制。

┌──────────────┐        ┌─────────────┐        ┌─────────────┐        ┌──────────────┐
│  输入文档     │  解析   │    AST      │  过滤   │  修改后 AST  │  输出   │  目标文档     │
│ (Markdown)   │ ─────→ │ (抽象语法树) │ ─────→ │            │ ─────→ │  (.docx等)   │
└──────────────┘        └─────────────┘        └─────────────┘        └──────────────┘
                                                     ↑
                                                     │
                                              ┌──────┴──────┐
                                              │ Lua 过滤器   │
                                              │ (.lua 文件)  │
                                              └─────────────┘

Lua 过滤器相比 JSON 过滤器的优势：

⚡ 更快的执行速度：内置解释器，无需进程间通信
📦 零外部依赖：不需要安装 Python、Node.js 等运行时
🔌 更强的功能：可以访问 Pandoc 的完整 API

实用示例——自动修复相对链接：

-- fix-links.lua: 将相对链接转换为绝对链接
function Link(el)
  if not el.target:match("^http") then
    el.target = "https://example.com/" .. el.target
  end
  return el
end

使用方式：

pandoc input.md -o output.html --lua-filter=fix-links.lua

📚 获取更多过滤器：官方的 pandoc/lua-filters 仓库正在逐步迁移到 pandoc-ext 组织。你可以直接下载 .lua 文件并通过 --lua-filter 参数使用，无需特殊安装。

💻 跨平台与轻量化

作为一款用 Haskell 编写的工具，Pandoc 可以在 Windows、macOS 和 Linux 上稳定运行，且不依赖大型办公软件即可生成高质量文档。

Pandoc 的技术特性：

单一可执行文件：安装包体积约 100MB，包含所有必要组件
无运行时依赖：不需要 Microsoft Office、LibreOffice 等软件
命令行友好：易于集成到自动化脚本和 CI/CD 流程中
活跃的开发社区：在 GitHub 上拥有超过 35,000 个星标，持续更新维护

适用场景

👨‍💻 程序员与技术作家

用 Markdown 编写文档，然后一键通过 Pandoc 的 GitHub Action 部署为美观的 HTML 或 PDF。

典型工作流示例：

# .github/workflows/docs.yml
name: Build Documentation
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker://pandoc/latex:latest
        with:
          args: >-
            --from=markdown
            --to=pdf
            --output=docs/manual.pdf
            docs/manual.md

为什么程序员偏爱 Pandoc？

📝 可以用熟悉的 Markdown 写作，专注于内容而非格式
🔄 版本控制友好：纯文本源文件便于 Git 追踪变更
🤖 自动化集成：可轻松嵌入 CI/CD 流水线
🎯 输出灵活：同一份源文件可生成网页文档、PDF 手册、Word 报告等多种形式

🎓 学生与学者

将复杂的 LaTeX 论文转换为易于导师批阅的 Word 格式，且保持引用和公式不乱码。

学术写作场景的具体价值：

📊 格式适配：不同期刊可能要求 LaTeX、Word 或 PDF 格式，Pandoc 让你只需维护一份源文件
📚 引用自动化：配合 Zotero/Mendeley 实现文献的自动引用和格式化
✍️ 专注写作：使用 Markdown 写初稿，避免在排版上浪费时间
🔢 公式保真：数学公式在格式转换中不会变形或丢失

基准测试数据：根据第三方测试，Pandoc 在处理包含表格的复杂文档时，文本准确率达到 98%，比许多在线转换工具高出约 30% 的保真度。

📖 电子书创作者

将分章节的文本文件合并并转换成标准的 EPUB 或 Kindle 格式。

电子书制作命令示例：

# 将多个 Markdown 章节合并为 EPUB
pandoc chapter1.md chapter2.md chapter3.md \
  --metadata title="我的书籍" \
  --metadata author="作者名" \
  --toc \
  --toc-depth=2 \
  -o mybook.epub

EPUB 生成的进阶选项：

--epub-cover-image=cover.jpg：设置封面图片
--epub-metadata=metadata.xml：添加出版元数据
--epub-chapter-level=1：控制章节分割级别
--css=style.css：应用自定义样式表

🏢 企业与团队协作

在企业环境中，Pandoc 同样发挥着重要作用：

文档标准化：统一公司内部文档的格式和样式
遗留文档迁移：批量转换旧格式文档（如 RTF、旧版 Word）为现代格式
多语言文档：支持从右到左书写的语言（阿拉伯语、希伯来语等）
无障碍合规：生成符合可访问性标准的 HTML 和 PDF 文档

如何开始？

第一步：安装程序 📥

访问 Pandoc 下载页面，根据操作系统下载安装包：

操作系统	安装方式
Windows	下载 `.msi` 安装包，双击运行向导安装
macOS	推荐使用 Homebrew：`brew install pandoc`
Linux (Debian/Ubuntu)	`sudo apt install pandoc` 或下载 `.deb` 包
Linux (Fedora)	`sudo dnf install pandoc`
跨平台	使用 conda：`conda install -c conda-forge pandoc`

验证安装：

pandoc --version
# 输出类似: pandoc 3.8.3

第二步：掌握基本命令 ⌨️

打开终端，输入简单的指令即可完成转换。

最常用的转换命令：

# Markdown → Word
pandoc input.md -o output.docx

# Markdown → HTML（独立文件，包含样式）
pandoc input.md -s -o output.html

# Word → Markdown
pandoc input.docx -o output.md

# HTML → Markdown
pandoc https://example.com/page.html -o output.md

# 多个文件合并转换
pandoc chapter1.md chapter2.md chapter3.md -o book.docx

常用参数说明：

参数	作用	示例
`-o`	指定输出文件	`-o report.pdf`
`-s`	生成独立文件（standalone）	包含完整的文档头部信息
`-f`	指定输入格式	`-f markdown`
`-t`	指定输出格式	`-t docx`
`--toc`	生成目录	自动创建 Table of Contents
`-V`	设置变量	`-V fontsize=12pt`
`--template`	使用自定义模板	`--template=mytemplate.latex`
`--lua-filter`	应用 Lua 过滤器	`--lua-filter=filter.lua`

第三步：PDF 转换进阶 📄

若需生成 PDF，Pandoc 需要借助外部排版引擎。根据你的需求，可以选择以下几种方案：

方案一：传统 LaTeX 引擎（推荐学术用户）

安装 TinyTeX（轻量级 LaTeX 发行版）或 MiKTeX：

# 安装 TinyTeX（推荐，约 100MB）
# macOS/Linux:
curl -sL "https://yihui.org/tinytex/install-bin-unix.sh" | sh

# Windows PowerShell:
Invoke-WebRequest -Uri "https://yihui.org/tinytex/install-bin-windows.bat" -OutFile "install.bat"; .\install.bat

然后使用 Pandoc 生成 PDF：

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

⚠️ 中文用户注意：处理中文文档时，建议使用 xelatex 或 lualatex 引擎，并在 YAML 头部指定中文字体：
---
mainfont: "Noto Serif CJK SC"
CJKmainfont: "Noto Serif CJK SC"
---

方案二：Typst 引擎（推荐追求速度的用户）🚀

Typst 是 2023 年出现的新一代排版系统，使用 Rust 编写，旨在取代 LaTeX。它的最大优势是编译速度极快。

性能对比（基准测试数据）：

引擎	编译时间（相对值）	特点
XeLaTeX	1x（基准）	功能完善，生态成熟
Typst	~27x 更快	现代语法，接近即时编译

使用 Typst 生成 PDF：

# 首先安装 Typst
# macOS:
brew install typst
# 或通过 cargo:
cargo install typst-cli

# 使用 Pandoc + Typst
pandoc input.md -o output.pdf --pdf-engine=typst

Typst 的优势：

⚡ 编译速度提升约 27 倍，接近即时反馈
📝 语法更现代，接近 CSS 的样式定义
🔄 增量编译，只重新处理变化的部分
📦 单一可执行文件，安装简单

Typst 的当前局限：

生态系统相比 LaTeX 仍较年轻
某些高度专业化的学术排版需求（如复杂的 TikZ 图形）可能仍需 LaTeX

💡 建议：如果你的文档不需要复杂的 LaTeX 包支持，强烈建议尝试 Typst。特别是在需要频繁预览的写作过程中，速度优势非常明显。

方案三：HTML 转 PDF 引擎

如果你更熟悉 CSS 样式，可以使用基于 HTML 的 PDF 引擎：

# 使用 WeasyPrint（需要 Python 环境）
pip install weasyprint
pandoc input.md -o output.pdf --pdf-engine=weasyprint

# 使用 wkhtmltopdf
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf

第四步：进阶工具推荐 🛠️

如果你不喜欢命令行，可以使用集成 Pandoc 的编辑器：

工具	类型	特点	Pandoc 集成方式
Typora	Markdown 编辑器	所见即所得，界面优雅	内置导出调用 Pandoc
Obsidian	知识库/笔记工具	双向链接，插件丰富	通过 Pandoc 插件导出
VS Code	代码编辑器	扩展生态完善	Markdown Preview Enhanced 等插件
RStudio	数据分析 IDE	R Markdown 深度集成	原生支持 Pandoc
Quarto	下一代科技出版系统	支持 Python/R/Julia，Pandoc 驱动	内置 Pandoc，是 R Markdown 的继任者

🌟 特别推荐 Quarto：这是由 Posit（原 RStudio 公司）开发的新一代科技出版系统，构建在 Pandoc 之上，支持 Python、R、Julia 等多种语言，是学术写作和数据科学报告的理想选择。

Pandoc 与其他工具的对比

在选择文档转换工具时，了解不同工具的定位有助于做出正确选择：

对比维度	Pandoc	Word “另存为”	在线转换工具	Microsoft MarkItDown
支持格式数	60+	约 10 种	通常 5-10 种	~15 种
转换质量	98% 准确率	中等，常有格式丢失	约 92%（简单文档）	面向 AI/LLM 优化
批量处理	✅ 原生支持	❌ 需手动	❌ 通常不支持	✅ 支持
自定义能力	✅ 模板+过滤器	❌ 有限	❌ 几乎没有	❌ 有限
引用支持	✅ 完整 CSL	❌ 仅基础	❌ 通常不支持	❌ 不支持
隐私安全	✅ 本地处理	✅ 本地	⚠️ 需上传文件	✅ 本地
适用场景	人类可读文档转换	简单格式转换	临时使用	AI/分析管道

Pandoc 的主要优势总结：

📊 更高的转换保真度
🔧 高度可定制
🔒 数据不离开本地
🤖 易于自动化集成

常见问题与解决方案

❓ 中文 PDF 显示为方块或乱码

原因：默认 LaTeX 引擎不包含中文字体。

解决方案：

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

或在文档 YAML 头部添加：

---
documentclass: ctexart
---

❓ 表格在转换后变形

原因：不同格式对表格的支持程度不同。

解决方案：

使用 Pandoc 的 pipe_tables 或 grid_tables 扩展
对于复杂表格，考虑使用 --wrap=none 避免自动换行

❓ 代码高亮不生效

解决方案：

pandoc input.md -o output.html --highlight-style=pygments
# 可选样式: pygments, kate, monochrome, breezeDark, haddock, zenburn, tango

❓ 如何保留 Word 文档的样式？

解决方案：使用参考文档：

# 首先创建一个样式参考文档
pandoc -o custom-reference.docx --print-default-data-file reference.docx

# 编辑 custom-reference.docx 的样式后，转换时引用它
pandoc input.md --reference-doc=custom-reference.docx -o output.docx

实战案例：完整的学术论文工作流

以下是一个使用 Pandoc 进行学术写作的完整示例：

1. 项目结构

my-paper/
├── paper.md          # 论文正文（Markdown）
├── references.json   # 文献数据（CSL JSON，从 Zotero 导出）
├── apa.csl          # 引用样式
├── template.latex    # 自定义 LaTeX 模板
└── figures/          # 图片文件夹

2. 论文源文件 (paper.md)

---
title: "论文标题"
author: "作者姓名"
date: "2026年1月"
abstract: "这是摘要内容..."
bibliography: references.json
csl: apa.csl
---

# 引言

根据 @smith2023 的研究，人工智能正在改变学术写作的方式。

# 方法

$$ E = mc^2 $$

# 结论

详见 [@jones2024; @wang2025]。

# 参考文献

3. 生成最终文档

# 生成 Word 版本（供导师批阅）
pandoc paper.md -o paper.docx --citeproc

# 生成 PDF 版本（正式提交）
pandoc paper.md -o paper.pdf --citeproc --pdf-engine=xelatex

# 生成 HTML 版本（在线分享）
pandoc paper.md -o paper.html --citeproc -s --mathjax

总结

如果你需要处理各种杂乱的文档格式，或者追求极致的文档自动化流程，Pandoc 绝对是你工具箱里最不可或缺的一把”瑞士军刀”。它的核心价值在于：让你专注于内容创作，而将格式转换的繁琐工作交给工具自动完成。

快速行动建议：

🔧 现在就去 pandoc.org 安装 Pandoc
📝 用 Markdown 写一篇简单文档
⚡ 尝试将它转换为 Word、PDF 和 HTML
🎯 逐步探索模板、过滤器和引用功能

延伸学习资源

📖 Pandoc 官方用户手册：最权威的参考文档
🎓 Customizing Pandoc (Learn by Example)：实用的定制化教程
🔧 Pandoc Lua Filters 官方文档：深入学习过滤器开发
📚 R Markdown Cookbook：R 用户的 Pandoc 实践指南
💬 Pandoc 讨论组：获取社区帮助

抱歉，回覆主題必需先登入。