Pandoc 使用文档

01 · Quick Start

快速开始

安装完成后的五分钟上手指南。

1. 安装 Pandoc

从下载中心获取对应平台安装包，或通过包管理器一键安装。安装后打开终端执行 pandoc --version 验证。

2. 编写源文档

用任意文本编辑器（VS Code、Typora、Vim）创建 hello.md，写入 Markdown 内容并保存。

3. 执行转换

在终端运行 pandoc hello.md -o hello.docx，几秒后即可在当前目录看到 Word 输出文件。

# 查看版本
pandoc --version

# 简单转换
pandoc hello.md -o hello.html
pandoc hello.md -o hello.docx
pandoc hello.md -o hello.pdf

# 查看帮助
pandoc --help
pandoc --list-input-formats
pandoc --list-output-formats

02 · Installation

各平台安装指南

三大主流操作系统的详细安装步骤说明。

Windows 安装指南

1

下载 MSI 安装包

从下载中心获取 pandoc-3.5-windows-x86_64.msi，建议保存至下载目录。

2

运行安装器

双击 MSI 文件启动安装向导，按提示选择安装路径（默认 C:\Program Files\Pandoc），完成安装。

3

验证 PATH 配置

安装器会自动将 Pandoc 路径加入系统 PATH。打开新的 PowerShell 或 CMD 窗口，执行 pandoc --version，如输出版本号即代表安装成功。

4

（可选）安装 PDF 引擎

如需输出 PDF，建议安装 MiKTeX 或 TeX Live，Pandoc 会自动识别系统中的 xelatex 引擎。

macOS 安装指南

1

下载 PKG 安装包

从下载中心获取 pandoc-3.5-mac-universal.pkg，该包为 Universal 通用格式，同时支持 Apple Silicon 与 Intel 芯片。

2

运行安装

双击 .pkg 文件，按提示完成安装。Pandoc 会被安装至 /usr/local/bin/pandoc，并自动配置好系统 PATH。

3

验证安装

打开终端（Terminal.app），执行 pandoc --version，输出当前版本号即表示安装成功。

4

（可选）Homebrew 方式

开发者可使用 brew install pandoc 一键安装，方便后续通过 brew upgrade 升级。

Linux 安装指南

1

选择安装方式

主流发行版均可通过包管理器直接安装：apt（Debian/Ubuntu）、dnf（Fedora）、pacman（Arch）。如需最新版本可下载预编译二进制。

2

安装二进制包

下载 pandoc-3.5-linux-amd64.tar.gz，解压后将 pandoc 与 pandoc-server 复制到 /usr/local/bin。

3

赋予执行权限

执行 sudo chmod +x /usr/local/bin/pandoc 确保可执行权限正常。

4

验证安装

新开终端执行 pandoc --version，输出版本号即代表安装完成。如命令未找到，请检查 /usr/local/bin 是否在 PATH 中。

03 · Examples

常用命令示例

覆盖内容生产与发布的高频场景。

Markdown 转 Word

将 Markdown 文档转换为带样式的 Word 文档，自带目录与基本排版。

pandoc report.md -s --toc -o report.docx

生成中文 PDF

使用 XeLaTeX 引擎，配合思源宋体输出中文 PDF，是论文场景标配。

pandoc paper.md --pdf-engine=xelatex \
  -V CJKmainfont=NotoSerifSC \
  -o paper.pdf

生成独立 HTML

生成单文件 HTML（含 CSS、JS、图片 base64 嵌入），便于邮件或离线分发。

pandoc article.md -s --embed-resources \
  --standalone --toc \
  -c style.css -o article.html

制作 EPUB 电子书

生成带目录、元数据的 EPUB 3 电子书，可直接上架销售平台。

pandoc book.md -s --toc \
  --metadata title="我的书" \
  --metadata author="作者名" \
  -o book.epub

学术论文（含引用）

结合 BibTeX 与 CSL 样式，自动生成符合期刊规范的引用与参考文献。

pandoc paper.md --citeproc \
  --bibliography=refs.bib \
  --csl=ieee.csl \
  --pdf-engine=xelatex \
  -o paper.pdf

生成演示幻灯片

一份 Markdown 同时输出 reveal.js HTML 演示与 PowerPoint 文件。

# reveal.js HTML 演示
pandoc slides.md -t revealjs -s \
  -o slides.html

# PowerPoint 演示
pandoc slides.md -o slides.pptx

04 · Reference

常用格式对照表

典型格式互转对应的命令写法速查。

源格式	目标格式	命令示例
Markdown	Word	`pandoc in.md -o out.docx`
Markdown	HTML	`pandoc in.md -s -o out.html`
Markdown	PDF	`pandoc in.md --pdf-engine=xelatex -o out.pdf`
Markdown	EPUB	`pandoc in.md -s --toc -o out.epub`
Word	Markdown	`pandoc in.docx -t markdown -o out.md`
HTML	Markdown	`pandoc in.html -t markdown -o out.md`
Markdown	LaTeX	`pandoc in.md -o out.tex`
Markdown	PowerPoint	`pandoc in.md -o out.pptx`
Markdown	reveal.js 幻灯片	`pandoc in.md -t revealjs -s -o out.html`

05 · Advanced

模板与过滤器

面向定制化输出的进阶用法。

自定义模板

使用 --template 参数指定自定义模板文件，模板内可使用 $title$ 、 $body$ 、 $date$ 等变量，精确控制最终输出文档的版式与品牌元素。

# 使用自定义 HTML 模板
pandoc doc.md -s \
  --template=my-template.html \
  --metadata title="产品手册" \
  -o doc.html

# 查看默认模板用作参考
pandoc -D html

Lua 过滤器

Lua 过滤器允许在不修改源文档的前提下，对 Pandoc AST 进行任意改写。常见用途包括图表自动编号、术语统一、品牌字号注入、广告位插入等。

# 应用单个过滤器
pandoc doc.md --lua-filter=number.lua -o doc.html

# 多个过滤器按顺序应用
pandoc doc.md \
  --lua-filter=fig.lua \
  --lua-filter=term.lua \
  -o doc.html

06 · FAQ

常见问题

使用过程中高频遇到的问题与解决方案。

PDF 输出时报错 "pdflatex not found"，怎么办？

Pandoc 本身不直接生成 PDF，而是借助 LaTeX 引擎（pdflatex、xelatex、lualatex、tectonic 等）来完成。请按以下方式处理：

Windows 用户：安装 MiKTeX，安装过程会自动配置 PATH。
macOS 用户：安装 MacTeX 或轻量的 BasicTeX。
Linux 用户：sudo apt install texlive-xetex texlive-fonts-recommended。
如仅做轻量 PDF 转换，可使用 --pdf-engine=tectonic 替代方案。

生成的 PDF 中文字符显示为方块或缺字，如何解决？

这是 LaTeX 引擎缺少中文字体所致。请改用 XeLaTeX 引擎并显式指定中文字体：

pandoc doc.md --pdf-engine=xelatex \
  -V CJKmainfont=NotoSerifSC \
  -V mainfont=NotoSerifSC \
  -o doc.pdf

系统需先安装思源宋体（NotoSerifSC）或文鼎字体，可通过 fc-list :lang=zh 命令查看可用中文字体。

如何让生成的 Word 文档使用我们公司的品牌样式？

使用 reference docx 方案：先用 Word 创建一份符合品牌规范的空白文档 reference.docx（设置好字体、字号、颜色、样式），然后通过 --reference-doc 参数让 Pandoc 复用其样式：

pandoc doc.md --reference-doc=reference.docx -o out.docx

该方案同样适用于 .pptx 与 .odt 输出格式。

如何同时把多个 Markdown 文件合并为一本书？

直接按顺序在命令行传入多个输入文件即可，Pandoc 会自动按顺序合并：

pandoc ch01.md ch02.md ch03.md \
  --toc --metadata title="我的书" \
  -o book.epub

建议在每章开头使用 Markdown 一级标题（#）以便自动生成目录。

Pandoc 是否支持图片懒加载与压缩？

Pandoc 自身不进行图片压缩，但支持通过 Lua 过滤器对图片资源进行预处理。常见做法是先用 imagemagick 或 sharp 批量压缩图片目录，再通过过滤器批量替换 src 路径或追加 loading="lazy" 属性。

如何在 CI/CD 流水线中集成 Pandoc？

Pandoc 是无 GUI 的纯命令行工具，天然适合 CI/CD 环境。GitHub Actions、GitLab CI、Jenkins 均可通过包管理器或 Docker 镜像集成。典型用法：在 CI 中拉取仓库 Markdown 源，通过 Pandoc 转换为 PDF 或 HTML，作为构建产物归档或自动发布到文档站点。

Pandoc 与 GitBook、MkDocs 等工具的关系？

GitBook、MkDocs、Hugo、Jekyll 等工具主要面向"Markdown 到静态网站"的场景，专注站点生成与导航体验；Pandoc 则是底层格式转换引擎，覆盖范围更广（Word、PDF、LaTeX、EPUB 等）。许多静态站点生成器在内部直接调用 Pandoc 完成 Markdown 渲染，二者关系互补而非替代。

Resources

进阶学习资源

深入学习 Pandoc 的官方与社区资源。

官方使用手册

最权威的参数与扩展说明，覆盖每个版本的完整能力清单。建议作为日常查阅参考。

GitHub Wiki

包含社区过滤器与模板合集，遇到具体场景时建议先搜索是否已有现成方案可复用。

过滤器与模板生态

社区维护的 Lua 过滤器与 LaTeX/HTML 模板生态，覆盖学术出版、企业文档、电子书等场景。

开始你的第一次转换

立即下载 Pandoc，五分钟内即可完成第一个文档转换。