[Tool] Pandoc markdown 转 Word 便捷手册

2026.04.16 豆包/ChatGPT 生成

Pandoc markdown 转 Word 便捷手册

最简洁的操作步骤

# 生成模板文件
pandoc -o reference.docx --print-default-data-file reference.docx
# 执行转换（核心命令）
pandoc input.md -o output.docx --reference-doc=reference.docx --highlight-style=tango

目录

• Pandoc markdown 转 Word 便捷手册
  • 0. 前提
• 1. 安装 pandoc
  • 命令
  • 备注
• 2. 验证安装
• 3. 最简单转换（无样式控制）
• 4. 带代码高亮（推荐）
• 5. 指定中英文字体（重点）
  • 命令
  • 说明（关键点）
  • ⚠️ 常见坑
• 6. 彻底解决方案：使用模板（推荐生产环境）
  • 6.1 生成默认模板
  • 6.2 修改模板（关键步骤）
    • 必改项：
      • 1）Normal（正文）
      • 2）Heading 1 / 2 / 3
      • 3）Code（代码块）
      • 4）表格样式
  • 6.3 使用模板生成
  • ✅ 模板 vs 参数 对比
• 7. 最终推荐命令（生产级）
• 8. 批量转换（带模板）
• 9. 常见问题
  • 9.1 为什么字体还是乱？
  • 9.2 中文还是没用微软雅黑？
  • 9.3 代码块字体不对？
  • 9.4 报错“Could not find data file”？
• 10. 一句话结论（经验总结）

0. 前提

• 系统：Linux

• 已安装：Homebrew (Linuxbrew)

• 目标文件：input\.md

• 输出文件：output\.docx

---

1. 安装 pandoc

命令

brew install pandoc

备注

• 无需 root

• 自动安装依赖

• 安装后全局可用

---

2. 验证安装

pandoc --version

---

3. 最简单转换（无样式控制）

pandoc input.md -o output.docx

---

4. 带代码高亮（推荐）

pandoc input.md -o output.docx --highlight-style=tango

---

5. 指定中英文字体（重点）

命令

pandoc "input.md" -o "output.docx" \
  -V mainfont="Times New Roman" \
  -V CJKmainfont="Microsoft YaHei" \
  --highlight-style=tango

说明（关键点）

• mainfont → 控制 西文（ASCII）

• CJKmainfont → 控制 中文

• Pandoc 内部通过 Unicode 范围自动区分

⚠️ 常见坑

这个方式不是 100% 全局生效，以下情况会失效：

• 标题样式（Heading 1/2）

• 表格字体

• 代码块字体

• 引用块

👉 原因：Word 样式优先级 > Pandoc变量

---

6. 彻底解决方案：使用模板（推荐生产环境）

6.1 生成默认模板

pandoc -o reference.docx --print-default-data-file reference.docx

关键说明：--print-default-data-file 后仅能跟 Pandoc 内置模板名（如 reference.docx），不可填写自定义文件路径，否则会报“Could not find data file”错误。

---

6.2 修改模板（关键步骤）

用 Word 打开 reference\.docx，修改以下样式：

必改项：

1）Normal（正文）

• 中文字体：微软雅黑

• 英文字体：Times New Roman

2）Heading 1 / 2 / 3

同样设置中英文字体

3）Code（代码块）

推荐：

• Consolas（英文）

• 或等宽字体

4）表格样式

Table Normal

---

6.3 使用模板生成

pandoc input.md -o output.docx \
  --reference-doc=reference.docx \
  --highlight-style=tango

补充：若需使用自定义 Word 文件（如超高清云转码系统使用手册_V1.8.docx）作为模板，命令如下（对照自定义文件路径修改）：

pandoc input.md -o output.docx \
  --reference-doc="/home/suma/ai/8510_series_install_doc/docs/xStream2050_V1.6.69版本正式下发/03_功能说明/超高清云转码系统使用手册_V1.8.docx" \
  --highlight-style=tango

---

✅ 模板 vs 参数 对比

方式	控制力	推荐程度
\-V mainfont	弱	❌
reference\.docx（默认/自定义）	强（完全控制）	✅

---

7. 最终推荐命令（生产级）

pandoc "我的文档.md" -o "我的文档.docx" \
  --reference-doc=reference.docx \
  --highlight-style=tango

自定义模板版本（替换为你的文件路径）：

pandoc "我的文档.md" -o "我的文档.docx" \
  --reference-doc="/home/suma/ai/8510_series_install_doc/docs/xStream2050_V1.6.69版本正式下发/03_功能说明/超高清云转码系统使用手册_V1.8.docx" \
  --highlight-style=tango

---

8. 批量转换（带模板）

for file in *.md; do
  pandoc "$file" -o "${file%.md}.docx" \
    --reference-doc=reference.docx \
    --highlight-style=tango
done

自定义模板批量转换（替换路径）：

for file in *.md; do
  pandoc "$file" -o "${file%.md}.docx" \
    --reference-doc="/home/suma/ai/8510_series_install_doc/docs/xStream2050_V1.6.69版本正式下发/03_功能说明/超高清云转码系统使用手册_V1.8.docx" \
    --highlight-style=tango
done

---

9. 常见问题

9.1 为什么字体还是乱？

根因通常是：

• Word 样式覆盖了 Pandoc 参数

👉 解决：必须用 reference.docx（默认/自定义模板）

---

9.2 中文还是没用微软雅黑？

检查：

fc-list | grep "Microsoft YaHei"

Linux 没装字体的话，需要先安装。

---

9.3 代码块字体不对？

模板里修改：

• Source Code 样式

---

9.4 报错“Could not find data file”？

根因：--print-default-data-file 后填写了自定义文件路径（而非内置模板名 reference.docx）。

👉 解决：生成默认模板用命令 pandoc \-o reference\.docx \-\-print\-default\-data\-file reference\.docx；使用自定义模板用 --reference-doc 参数（而非 --print-default-data-file）。

---

10. 一句话结论（经验总结）

• **\-V mainfont****临时用 → **

• reference\.docx****长期用 → （默认/自定义，唯一正确解）

• 禁止用 → --print-default-data-file + 自定义文件路径（必报错）

（注：文档部分内容可能由 AI 生成）