
md2word
在 Windows + Microsoft Word 流水线中把 Markdown 稳定导出为 Word,支持模板复用、图片、表格、Mermaid 和 Office Math 后处理。
- GitHub stars
- 15
Install
/plugin install md2word@cp-yu-md2wordRun it inside Claude Code after adding the marketplace with /plugin marketplace add cp-yu/md2word.
Contents
Discovered from sourceSkills 1
md2word
目标:
Markdown -> MHT -> DOCX -> WordMath DOCX
这个 skill 默认面向 Windows 直接运行。内置模板只是 fallback,不要把它理解成“只能导出专利交底书”。
入口判断
- 用户已经给了
.mht模板 - 用户已经给了
.docx模板,希望复用现有 Word 样式 - 用户没有模板文件,只有一段“模板长什么样”的文字描述
- 用户要求论文格式、标题字号、行距、封面结构等版式约束
- Markdown 里有
$...$、$$...$$、Mermaid 代码块,且最终必须落到 Word
环境要求
- 在 Windows 中运行
- PowerShell 可用
- Windows 桌面版 Microsoft Word 已安装,且 COM 可用
- Python 3 可通过
py -3、python或python3调起 - 代码块语法高亮默认依赖 Python
pygments;未安装时自动回退为可编辑纯文本代码块 - 如果 Markdown 含 Mermaid:
- 优先复用本机已有
mmdc - 否则允许
npx -p @mermaid-js/mermaid-cli mmdc - 首次
npx兜底可能需要联网下载
- 优先复用本机已有
输入约定
- 行内公式保持
$...$ - 行间公式保持
$$...$$ - 本地图片使用标准 Markdown 语法:
 - 标准 Markdown 表格会被渲染成 Word 表格
- Markdown 头字段支持两种写法:
**标题:** 示例文档标题: 示例文档
- 如果字段区后紧跟空行或
# 标题,正文也会被正确识别,不要求一定写--- - 标题优先从
标题/题目/主题取值;没有时再回退到发明名称/项目名称 - 正文 Markdown 标题会映射为 Word 正文标题层级,可在导航窗格中看到
- 默认只有正文章节标题进入导航;封面或文档主标题不进入导航
- 已显式写出的标题编号会保留;只有无编号标题才会做最小自动补号
工作流
- 按模板来源三选一分流:
.mht:直接使用.docx:先归一化导出为.mht- 模板规格/文字描述:先生成可复用
.mht
- 用
render_mht.py把 Markdown 填进模板。 - 调 Windows Word 打开 MHT,另存成
.docx。 - 在 Word 内把 LaTeX 文本转换成 Office Math,输出
.wordmath.docx。
模板与样式
- 如果用户给模板文件,优先复用模板,不要重造
- 如果用户只给一句模板描述,先写成
template-spec.md再传给--template-spec - 模板规格参考:
resources/template-spec.md - 当前内置样式预设:
defaultacademic-paper
- 静态模板、模板规格和样式预设统一放在
resources/ - 用户明确给出论文标题字号、标题层级、正文行距时,优先:
- 在模板规格里写
style-preset: academic-paper - 调用时再显式传
--style-preset academic-paper
- 在模板规格里写
正文插入策略
- 如果模板里有
{{CONTENT}}或<!--MD_CONTENT-->,优先按占位符替换 - 如果模板里有
{{METADATA_TABLE}},会把 Markdown 头字段渲染成信息表 - 如果模板里已有表格标签,例如
项目名称、电话、版本,会按行标签尝试填值 - 如果没有显式占位符,会推断
WordSection,优先替换最后一个正文 section - 推断过程可通过
--template-report输出报告
命令
使用内置默认模板:
<skill-dir>\scripts\md2word.cmd `
--input disclosure.md
使用模板规格生成模板:
<skill-dir>\scripts\md2word.cmd `
--input example.md `
--template-spec template-spec.md `
--template-out generated-template.mht `
--template-report template-report.md
生成学术论文格式:
<skill-dir>\scripts\md2word.cmd `
--input example.md `
--template-spec template-spec.md `
--template-out academic-paper.mht `
--template-report academic-paper.report.md `
--style-preset academic-paper
使用现成 Word 宏而不是内置公式转换:
<skill-dir>\scripts\md2word.cmd `
--input disclosure.md `
--macro-name "LatexToWordMath_Better"
直接调用 Python 主脚本:
py -3 <skill-dir>\scripts\md2word.py `
--input disclosure.md `
--style-preset academic-paper
关闭代码语法高亮、只导出可编辑纯文本代码块:
<skill-dir>\scripts\md2word.cmd `
--input disclosure.md `
--code-render-mode editable-code
兼容旧的 PowerShell 包装入口:
powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\md2word.ps1 `
-Input disclosure.md `
-StylePreset academic-paper
公式与 Mermaid
render_mht.py会把 Markdown 图片作为 MHT 关联资源打包进去- 标准 Markdown 表格会转成正文 Word 表格,并保留基本对齐方式
- 代码块默认用 Pygments 做语法高亮(
highlighted-code模式),带背景、边框和[语言]标签;未装pygments时自动回退为可编辑纯文本;可用--code-render-mode editable-code强制纯文本 render_mht.py会把 Mermaid 代码块渲染成图片插入 MHTrender_mht.py会归一化模板页脚里的PAGE/NUMPAGES布局,避免页码和总页数被拆成两段- 当前 Mermaid 渲染默认写入保守的 Puppeteer 配置,规避
headless shell在受限环境下失败 md2word.py会在生成的 DOCX 中把 Markdown 标题映射回 Word Heading 样式和大纲级别word_mht_pipeline.ps1会把常见块公式环境归一化后再交给 WordBuildUp- 当前已覆盖这些块环境:
matrixpmatrixbmatrixBmatrixvmatrixVmatrixcases
- Word 不支持把
\begin{matrix}...\end{matrix}原样直接 BuildUp;要先转成\matrix{...}或外层加分隔符
附带文件
scripts/md2word.py:Python 主入口,统一编排模板分流、渲染和 Word 流水线scripts/md2word.cmd:Windows 命令行包装器,转发到 Python 主入口scripts/md2word.ps1:PowerShell 兼容包装器,转发到 Python 主入口scripts/pipeline_common.py:主入口共享的参数校验、路径规划和文件校验逻辑scripts/render_mht.py:渲染 MHT、处理正文和 Mermaidscripts/generate_template_mht.py:从模板规格生成可复用 MHT 模板scripts/style_presets.py:统一加载样式预设配置scripts/word_common.ps1:Word worker 共享的 COM 清理与路径 helperscripts/word_template_to_mht.ps1:DOCX 模板归一化为 MHTscripts/word_mht_pipeline.ps1:Word 导出与 Office Math 转换resources/template-spec.md:模板规格参考resources/style-presets.json:样式预设配置resources/专利交底书模板.mht:默认 fallback 模板
失败处理
- 如果 PowerShell、Python 或 Word COM 不可用,不要假装 Windows 之外能补全最终 Word 效果,直接报环境问题
- 如果 Mermaid 渲染失败,先看是否有本机
mmdc;没有的话确认是否允许npx下载 - 如果模板效果不对,先看
--template-report - 如果公式异常,先区分:
- 原始
.docx已经错:问题在 MHT 或公式文本归一化 - 原始
.docx正常、.wordmath.docx才错:问题在 WordBuildUp
- 原始
- 如果矩阵类公式再次出问题,先检查传给 Word 的线性格式是否已经被归一化成
\matrix{...}族,而不是残留\begin{...}/\end{...}
Sponsors
Details
- Marketplace
- cp-yu/md2word
- Author
- cp-yu
- Category
- Document Processing
- License
- MIT