安装和使用pandoc

一、Pandoc 是什么？

1. 核心特性

• 格式互通：支持 Markdown、DOCX、LaTeX、HTML、PDF、EPUB 等 60+ 种格式 的互相转换
• 模块化处理：通过 filter 插件机制（如 Lua/Python）实现自定义处理逻辑（如公式替换、表格重排）
• 学术强化：
  • 无缝支持 LaTeX 数学公式（$E=mc^2$ → PDF 原生渲染）
  • 自动生成目录、图表编号（--toc 参数）
  • 引用文献管理（整合 BibTeX、Zotero）

2. 技术原理

Pandoc 内部使用 抽象语法树（AST） 机制：

[输入格式] → [解析器 → AST] → [输出生成器] → [目标格式]

这意味着转换过程并非简单的文本替换，而是结构化重整（例如将 Word 的标题映射为 LaTeX 的 \section{}）

3. 典型用例

• 学术写作：Markdown 转 LaTeX/PDF（保持公式和参考文献）
• 电子书制作：批量转换 HTML/EPUB
• 文档自动化：用 YAML 元数据控制 PDF 样式

二、Pandoc 安装指南

1. 主流系统安装

Windows：

1. 下载官方安装包：pandoc.org/installing.…
2. 勾选 "Add to PATH" 确保命令行可用

macOS：

# 通过 Homebrew 安装（推荐）
brew install pandoc

# 安装 TeX 引擎（如需生成 PDF）
brew install --cask mactex

Linux：

# Debian/Ubuntu
sudo apt-get install pandoc texlive-latex-base

# RHEL/CentOS/AlmaLinux
sudo yum install pandoc texlive-scheme-basic

2、离线安装

步骤 1：下载离线包

• Pandoc 主程序：

  • 官网离线包：https://github.com/jgm/pandoc/releases
  • 选择 .msi 文件（如 pandoc-3.1.12-windows-x86_64.msi）

• LaTeX 环境（可选，如需生成 PDF）：

  • MiKTeX 离线安装包：Getting MiKTeX
  • 下载 Net Installer 或 Complete 版本（约 1GB）

步骤 2：安装

1. 双击 .msi 安装 Pandoc（勾选 “Add to PATH”）
2. 安装 MiKTeX（完整版勾选所有组件）

3、验证安装：

pandoc --version
latex --version  # 检查是否识别

三、Pandoc 具体使用

1. 基础转换命令

通用语法：

pandoc [输入文件] -f [输入格式] -t [输出格式] -o [输出文件]

场景示例：

# Markdown → HTML（最简示例）
pandoc input.md -f markdown -t html -o output.html

# Word → Markdown（保留表格）
pandoc report.docx -t markdown-tables -o report.md

# LaTeX → PDF（自动渲染数学公式）
pandoc paper.tex -o paper.pdf --pdf-engine=xelatex

2. 高级功能参数

元数据控制：

# 用 YAML 文件定义标题、作者（metadata.yaml）
pandoc doc.md --metadata-file metadata.yaml -o doc.pdf

# 内联元数据
echo '% 标题: My Paper\n% 作者: John Doe\n\n正文' | pandoc -s -o out.docx

模板引擎：

# 使用自定义 LaTeX 模板
pandoc doc.md -o doc.tex --template=mytemplate.tex

# 输出前插入 CSS 样式（HTML）
pandoc doc.md -o doc.html --css=style.css

批量处理：

# 转换目录下所有 .md 文件到 HTML
find ./docs -name "*.md" -exec pandoc {} -o {}.html \;

3. 学术场景实战

需求：将 Markdown 学术文章转 PDF，要求：

• 包含目录、图表自动编号
• 引用参考文献（refs.bib）
• 使用 ACM 论文模板

步骤：

1. 准备 metadata.yaml：

   title: "My Research"
   author: "Jane Smith"
   date: "2023-10-01"
   bibliography: refs.bib
   csl: acm-sigchi.csl  # 引用格式文件
   

2. 执行转换：

   pandoc paper.md metadata.yaml \
     -o paper.pdf \
     --template=acm-template.tex \
     --pdf-engine=xelatex \
     --table-of-contents \
     --number-sections
   

4. 解决常见问题

中文乱码：

# 指定编码和字体
pandoc doc.md -o doc.pdf \
  --pdf-engine=xelatex \
  -V mainfont="SimSun" \
  -V CJKmainfont="楷体"

公式渲染失败：

<!-- 在 Markdown 中明确指定数学格式 -->
```math
E = mc^2

---

四、Pandoc 的底层扩展

1. 使用 Filter 扩展功能

Python 示例：自动转换图片链接到 LaTeX 代码

# imgfilter.py
from pandocfilters import toJSONFilter, Image

def convert_images(key, value, format, meta):
    if key == 'Image':
        # 将 ![alt](src) 转为 \includegraphics{src}
        return [{'t': 'RawInline', 'c': ['latex', f'\\includegraphics{{{value[2][0]}}}']}]

if __name__ == "__main__":
    toJSONFilter(convert_images)

应用 Filter：

pandoc doc.md --filter imgfilter.py -o doc.tex

2. 编程接口（Python）

import pypandoc

# 直接调用 Pandoc 引擎
output = pypandoc.convert_file(
    'input.docx', 
    to='markdown', 
    outputfile='output.md',
    extra_args=['--wrap=none']
)

---

总结：选择场景与效率

场景	推荐命令
快速格式转换	pandoc input.ext -o output.ext
学术论文（含公式/引用）	结合 --citeproc 和 LaTeX 模板
批量处理文档	搭配 find 或 Python 脚本
深度定制输出	使用 Lua/Filter 或自定义模板