使用 Pandoc 打造一套可复用的 Word 模板（docx）

Pandoc 是一款非常强大的文档转换工具，常用于将 Markdown 转换为 Word（docx）、PDF、HTML 等格式。在实际工程或文档规范化场景中，docx 模板（reference-docx）几乎是必不可少的。

本文将系统介绍：

• Pandoc 的 docx 模板工作原理
• 如何制作一个“Pandoc 友好”的 Word 模板
• 常见样式（标题、列表、代码、图片等）的正确设置方式
• 常见问题与踩坑总结

一、Pandoc 的 docx 模板原理

Pandoc 在生成 Word 文档时，并不是“复制现有 Word 内容”，而是：

根据 Markdown 结构，映射到 Word 的“样式（Style）”，再由样式决定最终外观

也就是说：

• Pandoc 只关心样式定义
• 不关心你在 Word 里对某一段“手工点出来”的格式

因此，Pandoc 的 docx 模板本质上是一个：

样式配置文件，而不是示例文档

二、reference-docx 是什么

Pandoc 通过参数指定 Word 模板：

pandoc input.md -o output.docx --reference-doc=template.docx

这个 template.docx 需要满足一个核心条件：

必须修改的是“内置样式”，而不是新增样式

Pandoc 只会识别 Word 内置样式，如：

• Heading 1 / Heading 2 / Heading 3
• Normal
• List Paragraph
• Source Code
• Caption
• Image Caption（Figure Caption）

三、推荐的模板制作流程

1. 生成一个基础模板（推荐）

让 Pandoc 先帮你生成一个“标准骨架”：

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

这个文件包含了 Pandoc 实际会使用的全部样式，是最佳起点。

2. 打开 reference.docx，进入“样式编辑模式”

在 Word 中：

• 打开“开始” → “样式”
• 右键样式 → 修改
• 通过“格式”按钮修改字体、颜色、段落等

不要直接选中文字去改颜色或字体

四、常见样式的正确设置方式

4.1 标题样式

Pandoc 将 Markdown 标题映射为 Word 内置的标题样式：

# 一级标题        → Heading 1
## 二级标题       → Heading 2
### 三级标题      → Heading 3

因此，必须修改 Word 的内置标题样式本身。

修改「标题样式本身」（推荐做法）

以下步骤以 Heading 1（标题 1） 为例，其他级别标题完全相同。

打开模板文件,使用 Word 打开你的模板文件

进入样式管理

1. 切换到 Word 顶部菜单 “开始”
2. 在“样式”区域找到 “标题 1”
3. 右键点击 “标题 1”
4. 选择 “修改”

注意：
不要选中正文里的某一行标题去改格式，这样 Pandoc 不会识别。

修改字体属性（颜色、字号等）

在“修改样式”窗口中：

1. 点击左下角 “格式”
2. 选择 “字体”
3. 设置你需要的属性，例如：
   • 字体：黑体 / Arial
   • 字号：16 pt
   • 颜色：红色 / 深蓝色
4. 点击“确定”

修改段落属性（间距、行距）

仍在“修改样式”窗口中：

1. 点击 “格式” → “段落”

2. 推荐设置：

   • 段前：12 磅

   • 段后：6 磅

   • 行距：单倍或 1.3 倍

3. 确认

步骤 关键选项（非常重要）

在“修改样式”窗口底部勾选： “基于该模板的新文档”

这一步决定了：

• Pandoc 生成的新 docx 是否真正使用你的样式

• 模板是否可复用

  保存模板

• 点击“确定”

• 保存 pandocmuban.docx

4.2 正文样式（Normal）

Pandoc 中的普通文本对应 Word 的 Normal 样式。

修改方法

1. 开始 → 样式
2. 右键 Normal → 修改
3. 设置：
   • 字体（如宋体 / 思源宋体）
   • 字号（10.5～12 pt）
   • 行距（1.3～1.5）
4. 勾选 “基于该模板的新文档”
5. 保存

4.3 无序列表 / 有序列表

Markdown 示例

- 第一项
- 第二项

1. 第一项
2. 第二项

对应 Word 样式

• List Paragraph
• Word 内置多级列表

修改步骤

1. 开始 → 样式
2. 找到 List Paragraph
3. 右键 → 修改
4. 点击 格式 → 段落
5. 建议设置：
   • 左缩进：0
   • 悬挂缩进：0.63 cm
6. 保存

不要在模板中手动输入 - 或 1.
列表符号由 Word 列表系统控制

4.4 行内代码（Inline Code）

Markdown 示例

这是 `inline code` 示例

对应 Word 样式

• Verbatim Char
• 或 Source Code Char（不同 Pandoc 版本略有差异）

修改方法

1. 样式窗格中找到对应字符样式
2. 右键 → 修改
3. 设置：
   • 等宽字体（Consolas / JetBrains Mono）
   • 字体颜色（深灰或蓝色）
4. 保存

4.5 代码块（Code Block）

Markdown 示例

```c
int main() {
    return 0;
}

#### 对应 Word 样式

- Source Code
- Code Block

#### 修改步骤

1. 右键 **Source Code** → 修改
2. 设置：
    - 等宽字体
    - 左右缩进
    - 行距略小
3. 可选：浅灰背景（不建议太深）

### 4.6 图片与图片说明

#### Markdown 示例

```markdown
![系统架构图](arch.png)

对应 Word 样式

• 图片本身：普通段落
• 图片说明：Figure Caption / Caption

修改建议

1. 修改 Caption / Figure Caption
2. 设置：
   • 字号小于正文
   • 灰色字体
   • 居中对齐

4.7 表格与表格标题

Markdown

| A | B |
|---|---|
| 1 | 2 |

Pandoc 会使用：

• Table
• Table Caption

建议：

• 统一表头加粗
• 设置单元格内边距
• 不要依赖手工边框

4.8 核心原则总结

所有样式修改都遵循同一原则：

• 修改 样式
• 不修改 具体段落
• 使用 Word 内置样式
• 勾选 “基于该模板的新文档”

只要遵守这四点，Pandoc 的 docx 转换结果将稳定且可控。

五、resource-path 与模板的配合

当 Markdown 中包含图片时，需要确保 Pandoc 能找到资源路径：

pandoc input.md \
  --resource-path=".;./images" \
  --reference-doc=reference.docx \
  -o output.docx

注意：

• --resource-path 只能写一次

• 多个路径用 ;（Windows）或 :（Linux/macOS）

六、常见问题与踩坑总结

1. 标题颜色不生效

原因：
只修改了某个标题段落的颜色，而不是 Heading 样式。

解决：
右键修改 Heading 样式本身。

2. 自定义样式不生效

原因：
Pandoc 不识别你新建的样式名。

解决：
只修改 Pandoc 使用的内置样式。

3. 样式被 Normal 覆盖

原因：
Heading 样式继承了 Normal，但自身未显式设置属性。

解决：
在 Heading 样式中明确设置字体、颜色、段落。

七、结语

Pandoc + Word 模板的核心思想只有一句话：

Markdown 管结构，Word 样式管外观

只要牢牢遵守这一点，Pandoc 完全可以成为一套稳定、可复用、可自动化的文档生产工具。

如果你希望进一步深入：

• 样式与 Lua filter 联动
• 自定义样式映射