Markdown 转 Word（md-to-word）

把 Markdown 转成 Word 文档（.docx）。面向「中文技术方案 / 公文」场景：中文排版主题 + 三种图 （Mermaid、泳道图、HTML 架构图）+ LaTeX 公式，图统统渲染成图片嵌进文档，公式转成 Word 原生可编辑公式。

Node 实现，不下载 Chromium——复用机器上已有的 Chrome / Edge / Playwright 浏览器渲染图片。

安装

从 magic-skills 合集里只装本技能（--only md-to-word，不会连带装 magic-stack 引擎、hook 等其它技能）。两种源二选一，装出来的东西完全一样：

外网（任意机器）

curl -fsSL http://maven.vv.yunku.live/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash -s -- --only md-to-word

内网（能直连 172.16.2.100，更快）

curl -fsSL --noproxy '*' http://172.16.2.100:8081/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash -s -- --only md-to-word

• --noproxy '*' 用于绕开本机 socks 代理（all_proxy），否则裸 curl 会被代理劫持、连不上内网。
• 本技能没有独立安装包，随合集发布；--only 让合集安装器只装它。去掉 -s -- --only md-to-word 就是装整套。

装到 ~/.claude/skills/md-to-word。生产依赖随包解压到位——不需要 npm、也不需要联网； 装完立刻能用。整套安装（前置依赖、升级、卸载）见安装整套技能。

命令行使用

cd ~/.claude/skills/md-to-word

# 基本转换(省略输出名 → 同名 .docx)
node bin/md-to-word.js 设计方案.md

# 指定输出
node bin/md-to-word.js 设计方案.md 输出.docx

# 预览模式: 产出 <name>.preview.md, 把 lanes 块渲成内联 SVG(不需要浏览器)
node bin/md-to-word.js 设计方案.md --preview

参数	说明
input	输入 Markdown（必填）
output	输出 .docx（可选，默认同名）
--theme <名称>	排版主题（默认中文公文风）
--config <路径>	自定义 YAML 配置
--preview	只产出预览 md（lanes 渲成内联 SVG，不起浏览器）
--quiet	静默

想先看渲染效果再转：用 magic-debug 的 md(path) 打开「MD 预览」页， 三种图全渲染、源文件一改自动刷新，顶栏一键导出 Word。写完整篇才发现图错了，返工代价大得多。

支持的三种图

写法	用途	渲染方式
```mermaid	流程图 / 时序图 / 状态图 / 类图 / ER / 甘特	本地 mermaid.min.js 离线渲染
```lanes	泳道流程图（Mermaid 不支持）	纯 JS 布局出 SVG
<!-- figure:arch --> … <!-- /figure -->	架构图 / 部署图 / 拓扑图	裸 HTML 浏览器截图

三种最终都会变成 PNG 嵌进 .docx。怎么选、怎么写见 tech-diagrams—— 架构图必须用 figure:arch 标记包裹，否则只会被当普通 HTML 提取文字。

LaTeX 公式

行内 $…$ 与块级 $$…$$ 转成 Word 原生 OMML 公式（在 Word 里可继续编辑），不是图片。

排版主题

默认按中文公文习惯排：标题黑体、正文仿宋_GB2312 三号、固定行距 28 磅、首行缩进 2 字符、 表格仿宋四号、A4 页边距。要改直接编辑技能目录的 config.yaml，或 --config 指定自己的文件—— 磅→twip、字符缩进→twip 的单位换算已内建。

浏览器与字体

浏览器（只有渲染图片时才需要）按序查找：环境变量 PUPPETEER_EXECUTABLE_PATH → Playwright 装的 chromium → 系统 Chrome / Edge。找不到会给出明确指引；纯文字文档与 --preview 完全不需要浏览器。

中文字体按序查找：技能目录 fonts/ → 本机系统字体目录（Windows C:\Windows\Fonts， Linux /usr/share/fonts 等）。包里不带字体（微软雅黑 / 宋体 / 黑体三个文件约 47MB，且是 Microsoft 授权字体）；Windows 本机自带，效果一样。纯净 Linux 容器里若两处都没有，中文会按浏览器 默认字体渲染——要精确排版就把 ttf 放进技能的 fonts/ 目录。

常见问题

现象	处理
报找不到浏览器	装 Chrome / Edge，或设 PUPPETEER_EXECUTABLE_PATH 指向已有浏览器
架构图只出文字没出图	HTML 没用 <!-- figure:arch --> … <!-- /figure --> 包裹
Linux 容器里中文乱码/方块	装系统中文字体，或把 ttf 放进技能的 fonts/
.emf / .wmf 图不显示	矢量图元格式不支持，预先转成 PNG
要改字体字号行距	编辑 config.yaml 或 --config 指定自己的配置

已知限制

• .emf / .wmf 矢量图元格式不支持，请预先转成 PNG。
• 既无标记、又不含 <svg> / position:absolute 的复杂 HTML 只提取文字。
• 不支持分栏、自定义页眉页脚。

维护者

源码在 magic-skills 合集的 md-to-word/，随合集 tag 一起发版（见 安装整套技能 → 升级）。

• 刷新依赖：npm ci --omit=dev 后重新打包 deps/node-deps.tgz（仓里不放展开的 node_modules）。
• 跑测试：npm ci && npm test（150 个单元测试：解析 / 布局 / SVG / 单位换算 / 标记扫描 / HTML 图识别 / 公式转 OMML）。