Pandoc 是什么
Pandoc 是文档格式互转工具，支持 DOCX、HTML、EPUB、LaTeX、ODT 等到 Markdown 的转换，也能反向往排版格式输出。在 RAG 流程里它承担“统一入口”的角色：把来源格式杂乱的语料先转成 Markdown，让后续清洗与切分只面对一种格式。它是规则驱动的转换器，不依赖版面模型，速度极快，但对复杂 Word 样式与图文的映射能力有限。
基本信息
| 安装方式 | 系统包管理器或官方发行包，跨平台命令行工具 |
|---|---|
| 常用输入 | docx、html、epub、latex、odt、rst |
| 常用输出 | -t markdown、-t gfm（GitHub 风格）、-t json |
| 关键选项 | --wrap=none 保留原始换行，--extract-media 导出图片 |
| 定位 | 规则转换，不做版面分析 |
典型使用场景
- 内部 Word 手册入库：批量转 Markdown 后再切分，避免直接解析 docx
- 网页内容归档：把抓取的 HTML 转成干净 Markdown，去掉脚本与样式噪声
- 电子书拆章：EPUB 转 Markdown 按标题层级切，天然适配章节粒度
- 格式统一：多来源语料统一成同一套标题语法，切分器只需一套规则
- 内容对账：把同一份文档的两种格式分别转出，比对差异定位转换损耗
常用转换命令
常用转换命令
pandoc input.docx -t markdown --wrap=none -o output.md
pandoc input.html -t gfm --wrap=none -o output.md
pandoc input.epub -t markdown --wrap=none --extract-media=./media -o book.md
for f in *.docx; do pandoc "$f" -t markdown --wrap=none -o "${f%.docx}.md"; done # 批量选项与效果
| 选项 | 作用 | 注意点 |
|---|---|---|
| --wrap=none | 不按列宽重排换行 | 逐行敏感的处理必须先加 |
| -t gfm | GitHub 风格 Markdown | 表格与任务列表兼容性更好 |
| --extract-media | 导出嵌入图片 | 要决定图片入库还是丢弃 |
| -t json | 输出 AST 结构 | 适合写自定义解析逻辑 |
Pandoc 只看样式映射，不理解版面：扫描件、双栏 PDF、复杂表格它都无能为力，这类文档要交给版面分析工具，把 Pandoc 留给结构规整的文本型文档。
批量转换的工程注意点
- 先做格式盘点：统计每类格式的文件数与失败案例，避免一条规则套所有来源
- 保留原始文件：转换是有损的，出现问题时必须能回到源头重跑
- 失败要可见：逐文件记录退出码与产物大小，静默跳过的文件往往就是线上缺内容的原因
- 产物验收：抽检标题层级、表格行列数、正文行数三项指标是否与原始文件大致吻合