bitq-pandoc Skill 使用说明：让 Pandoc 转 Word 更稳

bitq-pandoc 是一个面向 Pandoc 文档工作流的 Skill，目标不是替代 Pandoc，而是把“Markdown 转 Word 后还要手工修格式”的痛点收敛成一套可重复执行的流程。它特别适合图表较多、需要交叉引用、并且最终要交付 .docx 的场景。

下载使用

如果你想直接下载这个 Skill，可以使用下面的压缩包：

• 下载 bitq-pandoc.skill.zip

下载后解压即可看到完整目录，包括 SKILL.md、脚本、默认模板、示例文档与兼容性说明。

这个 Skill 解决什么问题

在实际使用 Pandoc 输出 Word 时，常见问题通常不是“能不能导出”，而是“导出后还要不要再花时间修”。例如：

• 图片没有按预期居中
• 图表题注位置和样式不稳定
• 表格边框出现虚线或和模板风格不一致
• pandoc-crossref 生成的交叉引用虽然正确，但最终排版还不够规范

bitq-pandoc 的思路很简单：

• 继续用 Markdown 作为唯一真源
• 先用 Pandoc 负责生成基础 .docx
• 再用 Python 脚本做一次后处理修复

这样做的好处是，正文内容、图表引用和最终排版职责分离，后续维护更稳定。

Skill 目录结构

重构后的目录如下：

test/skills/bitq-pandoc/
├── SKILL.md
├── scripts/
│   └── fix_final.py
├── references/
│   └── compatibility.md
├── assets/
│   ├── reference.docx
│   └── examples/
│       └── test.md
└── tests/
    └── test_fix_final.py

各部分职责如下：

• SKILL.md：Skill 入口，定义触发描述、标准流程和使用规则
• scripts/fix_final.py：后处理脚本，修复图片、题注、表格对齐与边框
• references/compatibility.md：兼容性说明，只在版本或模板异常时再看
• assets/reference.docx：默认参考模板
• assets/examples/test.md：最小示例文档
• tests/test_fix_final.py：针对脚本命令行入口的聚焦测试

什么时候使用这个 Skill

当你遇到下面这些需求时，就适合触发 bitq-pandoc：

• 需要把 Markdown 转成 Word
• 文中包含图片、表格和交叉引用
• 使用了 pandoc-crossref
• 希望套用 reference.docx 做基础样式映射
• 输出后的 Word 还需要进一步稳定排版

如果只是简单把 Markdown 导出成 .docx，没有图表题注、模板样式或后处理需求，其实没必要强行用这个 Skill。

标准使用流程

第一步：生成基础 Word

先用 Pandoc 生成基础文档：

pandoc input.md --filter pandoc-crossref -o output.docx --reference-doc assets/reference.docx

这个阶段主要负责三件事：

• 解析 Markdown
• 生成图表题注和交叉引用文本
• 套用参考模板中的基础样式

第二步：执行后处理修复

再运行 Skill 自带脚本：

python scripts/fix_final.py output.docx output_fixed.docx

脚本目前会处理以下内容：

• 让图片所在段落居中
• 让图表题注居中
• 让表格整体居中
• 清理 Pandoc 留下的单元格边框
• 统一绘制黑色实线表格边框

第三步：人工验收

最终建议检查以下几项：

• 图片是否居中
• 图表题注是否居中
• 表格是否居中
• 表格边框是否是黑色实线
• 交叉引用文本是否正确

Markdown 规范说明

这个 Skill 的核心前提不是“先导出再修”，而是“先把 Markdown 写规范”。示例文件 test.md 就是一份最小规范样例，重点不是内容本身，而是图、表、题注、引用和 YAML 的组织方式。

1. 先写 YAML 头部

文档开头使用 YAML frontmatter，为 pandoc-crossref 提供题注和引用的基础配置：

---
title: Pandoc 交叉引用测试文档
author: bitq
chapters: true
chapDelim: "-"
figPrefix: 图
tblPrefix: 表
figureTitle: 图
tableTitle: 表
---

这些字段里最关键的是：

• figPrefix：控制图片引用前缀
• tblPrefix：控制表格引用前缀
• figureTitle：控制图片题注标题
• tableTitle：控制表格题注标题

如果你希望最终输出是中文“图 1”“表 1”这种风格，这些字段最好在源文档中统一写清楚。

2. 图片必须有唯一 ID

图片推荐直接使用标准 Markdown 图片语法，并在末尾追加 {#fig:...}：

![这是一张图片的题注，Pandoc 会自动将它放在图片下方](images/pic.png){#fig:my_logo}

这里有两个关键点：

• 题注直接写在 [] 中
• 图片 ID 使用 fig: 前缀，并保持全局唯一

正文中引用这张图时，使用：

正如[@fig:my_logo]所示，这是一张测试图片。

也就是说，图的定义和图的引用必须成对出现：

• 定义时用 {#fig:...}
• 引用时用 [@fig:...]

3. 表格题注写在表格下方

表格本体依旧使用标准 Markdown 管道表格：

| 姓名 | 年龄 | 测试得分 |
| :--- | :--- | :--- |
| 张三 | 28 | 95 |
| 李四 | 32 | 88 |

表格题注不是写在表头里，而是紧跟在表格后面，用冒号加题注加 ID：

: 这是一份测试人员的得分表格 {#tbl:data_table}

正文引用表格时，写法如下：

我们在[@tbl:data_table]中总结了一些测试数据。

这里的规则和图片完全对应：

• 表格定义使用 {#tbl:...}
• 表格引用使用 [@tbl:...]

4. 图和表的 ID 命名要稳定

建议长期保持以下命名约定：

• 图片一律使用 fig: 前缀
• 表格一律使用 tbl: 前缀
• ID 使用英文、数字、下划线或短横线
• 同一篇文档内不要重复

推荐写法：

fig:system_architecture
fig:experiment_result
tbl:data_table
tbl:ablation_result

不建议今天写 fig:logo，明天又改成 fig:logo1、fig:new_logo 这种随意命名，因为一旦正文中已经存在大量引用，后续维护会很乱。

5. 题注、引用、模板三者要分工明确

写源文档时可以这样理解：

• Markdown 负责内容、结构、图表 ID 和引用关系
• pandoc-crossref 负责把 ID 变成可见的题注和引用文本
• reference.docx 负责基础样式映射
• fix_final.py 负责最后的排版修复

这也是为什么本工作流强调“规范 Markdown 文档”而不是“在 Word 里不断手调”。

6. 一旦修改内容，优先回到 Markdown

如果新增了一张图、删除了一张表、或者调整了章节顺序，最稳妥的做法不是去 Word 里补编号，而是：

1. 修改 Markdown
2. 重新运行 Pandoc
3. 再运行 fix_final.py

这样图表编号、交叉引用和最终排版才会始终保持一致。

如何理解这个 Skill 的边界

bitq-pandoc 只负责一条明确工作流，不做额外扩展：

• pandoc-crossref 负责交叉引用和题注文本生成
• fix_final.py 负责后处理排版
• Markdown 仍然是唯一维护源

这意味着一件很重要的事：不要把生成后的 .docx 当成主要编辑源。正确做法是回到 Markdown 修改后重新执行整条流程，而不是在 Word 里长期手工修补。

使用时的注意事项

1. 注意 Pandoc 与 pandoc-crossref 的兼容性

如果图表编号、题注或者交叉引用文本出现异常，优先排查版本组合，而不是先怀疑 Markdown 写法。

2. 不要依赖 Word 的 F9 域更新

这个工作流不是基于 Word 域代码驱动编号，而是让 pandoc-crossref 直接生成题注与引用文本，所以不建议把 F9 当作主要修复手段。

3. 模板决定基础风格，脚本负责最后修正

reference.docx 控制的是基础样式映射；脚本解决的是 Pandoc 导出后常见但重复的排版问题。这两层职责不要混在一起理解。

小结

bitq-pandoc 本质上是把一套个人经验沉淀成可复用 Skill：先转换，再修复，最后验收。这样做既能保留 Pandoc 的自动化优势，又能减少 Word 成品阶段的重复体力劳动。

如果你也在维护 Markdown 到 Word 的正式文档工作流，这个 Skill 很适合作为一个稳定起点。