Pandoc 万能格式转换¶

一句话概述：Pandoc 是文档格式转换的瑞士军刀，能在 Markdown、LaTeX、Word、HTML、PDF 等几十种格式之间自由转换。

核心知识点¶

概念	白话解释
Pandoc	格式转换器 = 万能文档翻译官
Reader	读取器 = 理解输入格式
Writer	写入器 = 生成输出格式
Filter	过滤器 = 中间处理（Lua/Python）
Template	模板 = 控制输出的排版样式
CSL	引文样式 = 控制参考文献格式

安装配置¶

# Linux
sudo apt install pandoc                                # Ubuntu/Debian
sudo dnf install pandoc                                # Fedora

# macOS
brew install pandoc                                    # Homebrew

# 验证
pandoc --version                                      # 查看版本（推荐 3.x）
pandoc --list-input-formats                            # 列出支持的输入格式
pandoc --list-output-formats                           # 列出支持的输出格式

常用转换¶

# === Markdown → 其他格式 ===
pandoc input.md -o output.docx                        # Markdown → Word
pandoc input.md -o output.pdf                         # Markdown → PDF（需要 LaTeX）
pandoc input.md -o output.html --standalone           # Markdown → 完整 HTML
pandoc input.md -o output.tex                         # Markdown → LaTeX
pandoc input.md -o output.pptx                        # Markdown → PPT

# === 其他格式 → Markdown ===
pandoc input.docx -o output.md                        # Word → Markdown
pandoc input.html -o output.md                        # HTML → Markdown
pandoc input.tex -o output.md                         # LaTeX → Markdown
pandoc input.epub -o output.md                        # EPUB → Markdown

# === 格式间互转 ===
pandoc input.docx -o output.pdf                       # Word → PDF
pandoc input.tex -o output.docx                       # LaTeX → Word
pandoc input.md -o output.epub                        # Markdown → EPUB

# === 使用 Typst 引擎生成 PDF（极快） ===
pandoc input.md -o output.pdf --pdf-engine=typst      # 用 Typst 代替 LaTeX

高级用法¶

# 带参考文献的学术文档
pandoc paper.md \
  --citeproc \                                        # 启用引文处理
  --bibliography=refs.bib \                           # 指定文献库
  --csl=apa.csl \                                     # 指定引文样式（APA）
  -o paper.pdf                                        # 输出 PDF

# 带目录的长文档
pandoc paper.md \
  --toc \                                             # 生成目录
  --toc-depth=3 \                                     # 目录深度
  --number-sections \                                 # 标题编号
  -o paper.pdf

# 合并多个文件
pandoc ch1.md ch2.md ch3.md \                         # 多个输入文件
  --toc \                                             # 生成目录
  -o book.pdf                                         # 合并为一本书

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

# YAML 元数据（在 Markdown 文件头）
# ---
# title: 我的论文
# author: 彭文强
# date: 2026-05-13
# geometry: margin=2.5cm
# fontsize: 12pt
# ---

Markdown 文件示例¶

---
title: 宏基因组分析报告
author: 彭文强
date: 2026-05-13
bibliography: refs.bib
csl: nature.csl
---

# 引言

肠道菌群与2型糖尿病密切相关 [@wang2022]。

# 方法

使用 MetaPhlAn4 进行物种注释。

# 结果

| 样本 | Shannon | Simpson |
|------|---------|---------|
| S1   | 3.21    | 0.89    |
| S2   | 2.98    | 0.85    |

# 参考文献

常见报错¶

报错	原因	解决
`pdflatex not found`	没装 LaTeX	安装 TeX Live 或用 `--pdf-engine=typst`
`Could not find image`	图片路径错	使用相对路径或绝对路径
`YAML parse error`	文件头格式错	检查 YAML 缩进和语法
`Citation not found`	bib 文件中没有该引用	检查 cite key 是否匹配
`UTF-8 encoding error`	编码问题	确保文件是 UTF-8 编码

速查表¶

# 基本用法
pandoc input -o output                                 # 自动识别格式
pandoc input -f FORMAT -t FORMAT -o output             # 显式指定格式

# 常用选项
# -o / --output           输出文件
# -f / --from             输入格式
# -t / --to               输出格式
# --standalone / -s        生成完整文档（不只是片段）
# --toc                    生成目录
# --number-sections        标题编号
# --citeproc               处理引文
# --bibliography=file.bib  指定文献库
# --csl=style.csl          指定引文样式
# --pdf-engine=xelatex     PDF 引擎（中文用 xelatex）
# --template=file          自定义模板
# --highlight-style=kate   代码高亮风格

# 常见格式代号
# markdown / gfm / commonmark / html / latex / docx / pdf / epub / pptx / rst