1 项目简介

P

Pandoc

通用文档转换器

Pandoc 是一个用 Haskell 编写的开源库和命令行工具，专门用于在不同标记格式之间进行转换。它被誉为文档格式转换的"瑞士军刀"，支持超过 50 种输入格式和 60 种输出格式。

41.8k+
GitHub Stars
557+
贡献者
50+
输入格式
60+
输出格式

关于项目

由 John MacFarlane 维护，采用 GPLv2+ 许可证发布。主要使用 Haskell (83.8%) 编写，项目始于 2006 年。

主要用途

  • 文档格式批量转换（Markdown → Word/PDF/HTML）
  • 学术论文排版（支持 LaTeX、BibTeX 引用）
  • 电子书制作（EPUB、PDF）
  • 演示文稿生成（reveal.js、Beamer）
  • Wiki 内容迁移（MediaWiki、DokuWiki 等）

2 架构概述

三阶段管道架构

Pandoc 采用模块化的三阶段管道设计，使得添加新格式只需实现 Reader 或 Writer，而无需为每对格式创建转换器。

📥
Reader
解析输入格式
🌳
AST
抽象语法树
📤
Writer
生成输出格式

技术栈

Haskell 83.8%
Roff 6.3%
RTF 4.8%
Lua 2.0%

3 支持格式

标记语言
Markdown CommonMark GFM AsciiDoc reStructuredText Org-mode Textile
文档格式
HTML DOCX ODT EPUB LaTeX JATS XML
Wiki/CMS
MediaWiki DokuWiki Jira Confluence
参考文献
BibTeX BibLaTeX CSL JSON RIS EndNote XML
其他
Jupyter Notebook CSV/TSV JSON YAML
网页
HTML4/5 XHTML Chunked HTML
文档
DOCX ODT EPUB v2/v3 PDF LaTeX ConTeXt RTF
演示文稿
PowerPoint Beamer reveal.js Slidy DZSlides
出版
DocBook 4/5 JATS XML TEI Simple ICML (InDesign)

4 核心功能

增强 Markdown

支持表格、定义列表、脚注、引用、数学公式、交叉引用等扩展语法

过滤器系统

支持 JSON 过滤器和内置 Lua 过滤器，可在转换过程中修改 AST

模板系统

支持自定义模板，使用变量、条件语句和循环控制输出格式

引用处理

内置 citeproc 支持，可处理 BibTeX 等参考文献并生成规范引用

5 安装配置

Homebrew（推荐）

brew install pandoc

MacPorts

port install pandoc

Conda

conda install -c conda-forge pandoc

PDF 支持

生成 PDF 需要安装 LaTeX。推荐使用 BasicTeX 或 TinyTeX（而非完整的 MacTeX，可节省 4GB 空间）。

Chocolatey

choco install pandoc

Winget

winget install --source winget --exact --id JohnMacFarlane.Pandoc

Conda

conda install -c conda-forge pandoc

PDF 支持

推荐通过 MiKTeX 安装 LaTeX 以支持 PDF 生成。

Debian/Ubuntu

# 使用系统包（可能不是最新版）
sudo apt install pandoc

# 或下载最新 .deb 包
sudo dpkg -i pandoc-x.x.x-amd64.deb

Arch Linux

sudo pacman -S pandoc

Fedora

sudo dnf install pandoc

从 tarball 安装

tar xvzf pandoc-x.x.x-linux-amd64.tar.gz --strip-components 1 -C /usr/local

基础用法

# 使用 pandoc/latex 镜像（包含 LaTeX）
docker run --rm --volume "`pwd`:/data" pandoc/latex README.md -o README.pdf

# 使用基础镜像
docker run --rm --volume "`pwd`:/data" pandoc/core README.md -o README.html

提示

pandoc/latex 镜像已包含完整的 LaTeX 环境，适合生成 PDF。

使用 Stack

stack setup
stack install pandoc-cli

使用 Cabal

cabal update
cabal install pandoc-cli

6 基础用法

基本语法

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

不指定文件时，从标准输入读取；不指定输出时，输出到标准输出。

常用转换示例

Markdown → HTML

pandoc input.md -o output.html

Markdown → Word 文档

pandoc input.md -o output.docx

Markdown → PDF（需要 LaTeX）

pandoc input.md -o output.pdf

Word → Markdown

pandoc input.docx -o output.md

HTML → Markdown

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

生成独立文档

使用 -s 或 --standalone 生成包含完整头部信息的独立文档：

pandoc -s input.md -o output.html

7 命令选项

选项 说明
-f, --from 指定输入格式
-t, --to 指定输出格式
-o, --output 输出到文件
-s, --standalone 生成独立文档（含头尾）
--template 使用自定义模板
-V, --variable 设置模板变量
-M, --metadata 设置文档元数据
-L, --lua-filter 应用 Lua 过滤器
-C, --citeproc 处理引用和参考文献
--toc 生成目录
--pdf-engine 指定 PDF 引擎（pdflatex/xelatex/lualatex 等）
--sandbox 沙箱模式（限制 IO 操作）

8 使用示例 

pandoc -s --toc -c style.css input.md -o output.html
pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="SimSun" \
  -V mainfont="Times New Roman"
pandoc paper.md -o paper.pdf \
  --citeproc \
  --bibliography=refs.bib \
  --csl=ieee.csl
pandoc -t revealjs -s slides.md -o slides.html \
  -V theme=moon \
  -V transition=slide
pandoc -o book.epub \
  --epub-cover-image=cover.jpg \
  --metadata title="我的书" \
  --metadata author="作者名" \
  chapter1.md chapter2.md chapter3.md
# 将目录下所有 .md 文件转为 HTML
for f in *.md; do
  pandoc "$f" -s -o "${f%.md}.html"
done

9 过滤器与扩展

Lua 过滤器

Lua 过滤器是内置的，无需额外依赖。可以在转换过程中修改 AST。

pandoc input.md -L filter.lua -o output.html

示例：将所有文本转为大写

-- uppercase.lua
function Str(elem)
  return pandoc.Str(string.upper(elem.text))
end

JSON 过滤器

可使用任何编程语言编写的外部脚本处理 AST。

pandoc input.md --filter ./myfilter.py -o output.html

格式扩展

可以启用或禁用特定格式的扩展功能：

# 启用 emoji 扩展，禁用删除线
pandoc -f markdown+emoji-strikeout input.md -o output.html

常用扩展：

+smart +emoji +footnotes +pipe_tables +task_lists +yaml_metadata_block

10 模板系统

查看默认模板

# 查看 HTML 默认模板
pandoc -D html

# 查看 LaTeX 默认模板
pandoc -D latex

模板语法

语法 说明
$variable$ 变量插值
$if(var)$...$endif$ 条件语句
$for(items)$...$endfor$ 循环语句
$body$ 文档主体内容

使用自定义模板

pandoc input.md -o output.html \
  --template=custom.html \
  -V title="我的文档" \
  -V author="作者"

11 高级功能

Defaults 文件

使用 YAML 配置文件保存常用选项：

# defaults.yaml
from: markdown
to: html
standalone: true
toc: true
metadata:
  author: "作者名"
variables:
  lang: zh-CN
pandoc -d defaults.yaml input.md -o output.html

数学公式渲染

--mathjax 使用 MathJax（推荐）
--katex 使用 KaTeX（更快）
--mathml 输出 MathML

资源路径

# 指定图片等资源的搜索路径
pandoc input.md -o output.html --resource-path=.:images:assets

退出码

代码 含义
0 成功
1 IO 错误
3 有警告
21-67 各类格式/处理错误