Pandoc 文档转换 Skill

Pandoc 是一个通用的文档转换工具，能够将多种标记格式相互转换，支持 50+ 种格式。

何时使用此 Skill

• Markdown 转 PDF、HTML、Word、LaTeX 等
• Word 转 Markdown、HTML、PDF
• HTML 转 Markdown、PDF、Word
• LaTeX 转 Markdown、HTML、PDF
• 批量文档格式转换
• 学术论文格式转换
• 电子书格式转换（EPUB 等）

基本语法

pandoc [选项] [输入文件]... -o [输出文件]

常用快捷命令

输入格式支持

• Markdown (.md, .markdown, .mdown)
• HTML (.html, .htm)
• LaTeX (.tex, .latex)
• Word (.docx)
• reStructuredText (.rst)
• Org-mode (.org)
• AsciiDoc (.adoc, .asciidoc)
• MediaWiki (.wiki)
• Textile (.textile)
• JSON (.json) - Pandoc JSON AST

输出格式支持

• PDF (需要 LaTeX 或 wkhtmltopdf)
• HTML / HTML5
• Word (.docx)
• LaTeX
• EPUB / EPUB3
• Markdown (多种变体)
• reStructuredText
• Org-mode
• AsciiDoc
• PowerPoint (.pptx)
• Jupyter Notebook (.ipynb)

常用选项

格式指定

# 明确指定输入格式
pandoc -f markdown input.txt -o output.pdf

# 明确指定输出格式
pandoc input.md -t html -o output.html

# 短格式别名
pandoc input.md -t pdf     # PDF
pandoc input.md -t docx    # Word
pandoc input.md -t html    # HTML
pandoc input.md -t latex   # LaTeX

PDF 生成引擎

# 使用 pdflatex (默认)
pandoc input.md -o output.pdf

# 使用 xelatex (支持中文更好)
pandoc input.md --pdf-engine=xelatex -o output.pdf

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

# 使用 wkhtmltopdf (HTML 转 PDF)
pandoc input.md --pdf-engine=wkhtmltopdf -o output.pdf

元数据设置

# 设置标题
pandoc input.md --metadata title="文档标题" -o output.pdf

# 设置作者
pandoc input.md --metadata author="作者名" -o output.pdf

# 使用 YAML 文件
pandoc input.md --metadata-file=meta.yaml -o output.pdf

模板使用

# 使用自定义模板
pandoc input.md --template=mytemplate.tex -o output.pdf

# 生成默认模板参考
pandoc -D latex > default-template.tex

目录和编号

# 生成目录
pandoc input.md --toc -o output.pdf

# 设置目录深度
pandoc input.md --toc --toc-depth=2 -o output.html

# 编号章节
pandoc input.md --number-sections -o output.pdf

引用和参考文献

# 使用 BibTeX 引用
pandoc input.md --citeproc --bibliography=refs.bib -o output.pdf

# 使用 CSL 样式
pandoc input.md --citeproc --csl=ieee.csl -o output.pdf

最佳实践

1. 中文 PDF 使用 xeLaTeX：--pdf-engine=xelatex 对中文支持更好
2. 先转 HTML 预览：复杂文档先转 HTML 检查格式，再转 PDF
3. 使用元数据文件：多文档批处理时使用 --metadata-file
4. 批量转换脚本：用 shell 脚本循环处理多个文件
5. 自定义模板：需要特定格式时导出默认模板修改

获取帮助

# 查看完整手册
pandoc --help

# 查看版本
pandoc --version

# 查看支持的格式
pandoc --list-input-formats
pandoc --list-output-formats

# 查看可用模板
pandoc --list-highlight-styles

# 查看默认模板
pandoc -D latex

故障排查

• PDF 生成失败：检查是否安装了 LaTeX (MacTeX, TeX Live, MiKTeX)
• 中文乱码：使用 --pdf-engine=xelatex 并确保字体可用
• 格式错乱：检查 Markdown 语法，先用 pandoc -t html 预览
• 引用不显示：确保使用 --citeproc 选项

相关资源

• 官方文档: https://pandoc.org/MANUAL.html
• 示例画廊: https://pandoc.org/demos.html
• 模板集合: https://github.com/pandoc/templates