Markdown 转 Word（md-to-word）

md-to-word 把 Markdown 文件转换为 Word 文档（.docx），特别适合中文内容 + Mermaid 流程图 + 统一样式主题的场景。

特性

• 完整 Markdown 支持——标题、列表、表格、代码块、图片、引用、分割线等。
• 离线 Mermaid 渲染——用本地 Mermaid.js + Playwright（Chromium）渲染流程图为图片，无需联网。
• 中文字体优化——内置微软雅黑、宋体、黑体等字体配置。
• 多主题——default / academic / business / minimal 四种预设。
• 可自定义——YAML 配置文件调整字体、标题、正文、代码、表格、Mermaid 样式。
• Python API——可作为模块导入使用。

安装

与其它技能一样以「绿色版制品」从 Nexus 分发，一行装——内网优先、外网兜底：

# 外网(任意机器)
curl -fsSL http://maven.vv.yunku.live/repository/raw-releases/md-to-word/latest/install.sh | bash

# 内网(能直连 172.16.2.100,更快)
curl -fsSL --noproxy '*' http://172.16.2.100:8081/repository/raw-releases/md-to-word/latest/install.sh | bash

安装器把整个技能解压到 ~/.claude/skills/md-to-word，并自动 pip install -r requirements.txt 且 playwright install chromium（Mermaid 渲染用）。依赖装失败不挡 skill 安装，按提示手动补齐即可。

从源码检出安装（开发 / 离线）：bash install.sh --local（就地铺 + 装依赖）； bash install.sh --no-deps（只铺 skill 文件，跳过 pip / playwright）。

命令行使用

在技能目录内执行 python converter.py：

# 基本转换(省略输出名 → input.docx)
python converter.py input.md output.docx

# 使用预设主题
python converter.py input.md output.docx --theme academic

# 自定义配置
python converter.py input.md output.docx --config my_config.yaml

# 下载 / 更新 Mermaid.js
python converter.py --download-mermaid

参数	说明
input	输入 Markdown 文件（必填）
output	输出 Word 文件（可选，默认同名 .docx）
--theme	预设主题：default（默认）/ academic / business / minimal
--config	自定义 YAML 配置文件路径
--download-mermaid	下载 Mermaid.js 到本地

主题

主题	适用	字体
default	一般文档	微软雅黑
academic	论文 / 学术报告	宋体 / Times New Roman
business	商务文档	紧凑排版 + 专业配色
minimal	阅读	简约

Python API

from converter import MarkdownToWordConverter

# 基本用法
converter = MarkdownToWordConverter()
converter.convert("input.md", "output.docx")

# 使用预设主题
converter = MarkdownToWordConverter(theme="academic")
converter.convert("input.md", "output.docx")

# 使用自定义配置
converter = MarkdownToWordConverter(config_path="my_config.yaml")
converter.convert("input.md", "output.docx")

配置

编辑 config.yaml（或用 --config 传自定义文件）可调整：字体（西文 / 中文 / 代码）、标题样式 （H1–H4 字体 / 大小 / 颜色 / 间距）、正文、代码块、表格、列表、Mermaid 主题。示例片段：

fonts:
  default:
    ascii: "Arial"        # 西文字体
    east_asia: "微软雅黑"  # 中文字体
    size: 12
headings:
  h1: { font: "黑体", size: 22, bold: true, color: "#000000" }
mermaid:
  theme: "default"        # default / dark / forest / neutral
  font_family: "微软雅黑"
  background_color: "#FFFFFF"

常见问题

现象	处理
中文字体显示异常	确保 fonts/ 目录含所需字体文件，config.yaml 中 east_asia 配置正确
Mermaid 图表无法渲染	跑 python converter.py --download-mermaid 下载 Mermaid.js；并确保已 playwright install chromium
图片无法显示	检查图片相对路径（基于 Markdown 文件位置）；支持 PNG / JPG / GIF / BMP / TIFF

发版（维护者）

打 tag 触发 CI 发布绿色版制品到 Nexus raw（与 magic-skills 同款，只走 CI）：

git tag v0.1.0 && git push origin v0.1.0    # CI publish:skill → md-to-word/<ver>/ + latest/