markdown2word

markdown2word · 学术场景优化的 Markdown → Word 转换 Skill

一个自包含的 Claude Code skill,把 Markdown 文档转换为**符合中文学术排版规范的 Word(.docx)**文件 —— 三线表、[n] 参考文献、一、/1.1/1.1.1/1.1.1.1 中文层级编号、黑体小四加粗的四级标题,一应俱全。

为什么"学术场景优化":通用 pandoc 转 docx 的产物在学术写作里几乎不可直接使用 —— 表格带完整框线、参考文献没有 [n] 编号、标题用 Word 默认西文字体、图与图注跨页分离。本 skill 针对这些痛点逐一改写:用 Lua 过滤器在 AST 层注入中文学术编号与图注绑定,用 Python 后处理器在 OOXML 层把表格边框重写为三线表、强制 H4 字体、给图段落加 keepNext 防止跨页,并提供 style.config 作为字体单一信息源。转换后还内置一道格式校验,任何一项不达标都以非零退出码告警。

---

学术排版特性

• 三线表(academic three-line table) —— 表层只保留上、下两条粗线,表头行下方一条细线;无竖线、无内部横线。sz=0 隐藏边框在 Word 里会渲染成虚影细线,因此一律省略声明而非置零。
• [n] 参考文献 —— ## 参考资料 / ## 参考文献 标题下的无序列表项自动编号为 [1]、[2]…,并套用 Reference 段落样式(同时去掉原 bullet ·)。
• 中文层级编号 —— H1 一、、H2 1.1、H3 1.1.1、H4 1.1.1.1,由 Lua 过滤器生成(pandoc 自带的 --number-sections 关闭,避免双重编号)。
• 四级标题样式 —— H4 强制为 黑体 / 小四(sz=24)/ 加粗 / 黑色(参考模板原本是斜体蓝色,被本配置覆盖)。
• 图表不跨页 —— 图片段落加 keepNext + keepLines,与紧随其后的图注锁定同页;图注段落加 keepLines,图注文字自身不拆行。
• 段落留白 —— 正文段后接标题时,标题前自动插入空行;每个图注后、每个表格后自动插入空行,视觉间距更接近论文排版。
• 字体单一信息源 —— 改 style.config(INI 格式)即可调整正文 / H1–H4 / 图注 / 表注 / 参考文献 的字体、字号、加粗、斜体、字色,无需改 Word 模板或 Python 代码。
• 无目录 —— 默认不带 TOC;若误生成了目录域,校验阶段直接判失败。

工作原理(两阶段流水线)

1. pandoc + Lua 过滤器(captions_refs_headings.lua):在 docx writer 之前的 AST 层处理 —— 图注绑定、[n] 参考文献编号、中文层级编号、H4 前导数字剥离。
2. Python 后处理器(postprocess_docx.py):重写 docx 内的 word/document.xml 与 word/styles.xml —— 三线表边框、ImageCaption→FigureCaption 重映射、表头跨页重复(tblHeader)、行不拆页(cantSplit)、图段锁定、空行留白、以及从 style.config 注入字体覆盖。

转换后还跑一道校验,逐项检查三线表边框、[n] 标记、H1 编号、H4 字体、是否误含 TOC;不达标则非零退出。

虽然设计为 Claude Code skill,流水线本身是纯 CLI 工具 —— convert.sh 脱离 Claude 也能独立使用。

前置依赖

PATH 上需要两个工具(Python 仅用标准库,无需 pip install):

pandoc --version    # pandoc 3.x
python --version    # Python 3.x

Windows 安装:winget install --id JohnMacFarlane.Pandoc,Python 3 从 python.org 下载。

用法

bash convert.sh report.md report.docx
# 省略第二个参数时,在输入文件旁生成同名 .docx:
bash convert.sh report.md

输出示例:

→ pandoc: report.md -> report.raw.docx
→ postprocess: report.raw.docx -> report.docx
→ verify: report.docx
  tables: 5 | refs: 17 | H1 num: True | H4 style: True | TOC: absent
  [OK] all formatting requirements met
done: report.docx

退出码	含义
0	转换 + 校验通过
1	已转换,但校验发现真实格式缺陷
2	用法错误、输入缺失、pandoc/python 缺失,或流水线文件缺失

自定义字体

编辑 style.config —— 区段 [body]、[h1]–[h4]、[figure_caption]、[table_caption]、[reference]。字号用「半磅」(Word 内部单位:24 = 12pt 小四、32 = 16pt 三号),字色用不带 # 的十六进制 RGB。

图注约定

图片段落后紧跟一个纯斜体段落(_图注文字_),该斜体段落会被绑定为图注并套用 FigureCaption 样式。若图注写在 ![alt] 里或非斜体段落里,则不会触发图注样式。

流水线文件

文件	作用
convert.sh	驱动脚本 —— 跑 pandoc + 后处理 + 校验
reference.docx	pandoc --reference-doc 样式模板(勿覆盖)
captions_refs_headings.lua	Lua 过滤器:图注、[n] 参考文献、中文编号
postprocess_docx.py	后处理器:三线表、图注重映射、字体覆盖
style.config	INI 字体/字号/字重/字色配置,应用到 styles.xml

作为 Claude Code skill 安装

把本目录复制(或软链)到 Claude Code 的 skills 目录:

# 项目级
cp -r markdown2word .claude/skills/markdown2word

# 或用户级
cp -r markdown2word ~/.claude/skills/markdown2word

之后对 Claude 说"把 report.md 转成 docx",即可触发本 skill。

许可证

MIT —— 见 LICENSE。