在 Windows + Microsoft Word 流水线中把 Markdown 稳定导出为 Word,支持模板复用、图片、表格、Mermaid 和 Office Math 后处理。

GitHub stars
15

Install

/plugin install md2word@cp-yu-md2word

Run it inside Claude Code after adding the marketplace with /plugin marketplace add cp-yu/md2word.

Contents

Discovered from source

Skills 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 语法:![说明](relative/path.png)
  • 标准 Markdown 表格会被渲染成 Word 表格
  • Markdown 头字段支持两种写法:
    • **标题:** 示例文档
    • 标题: 示例文档
  • 如果字段区后紧跟空行或 # 标题,正文也会被正确识别,不要求一定写 ---
  • 标题优先从 标题 / 题目 / 主题 取值;没有时再回退到 发明名称 / 项目名称
  • 正文 Markdown 标题会映射为 Word 正文标题层级,可在导航窗格中看到
  • 默认只有正文章节标题进入导航;封面或文档主标题不进入导航
  • 已显式写出的标题编号会保留;只有无编号标题才会做最小自动补号

工作流

  1. 按模板来源三选一分流:
    • .mht:直接使用
    • .docx:先归一化导出为 .mht
    • 模板规格/文字描述:先生成可复用 .mht
  2. 用 render_mht.py 把 Markdown 填进模板。
  3. 调 Windows Word 打开 MHT,另存成 .docx。
  4. 在 Word 内把 LaTeX 文本转换成 Office Math,输出 .wordmath.docx。

模板与样式

  • 如果用户给模板文件,优先复用模板,不要重造
  • 如果用户只给一句模板描述,先写成 template-spec.md 再传给 --template-spec
  • 模板规格参考:resources/template-spec.md
  • 当前内置样式预设:
    • default
    • academic-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 代码块渲染成图片插入 MHT
  • render_mht.py 会归一化模板页脚里的 PAGE/NUMPAGES 布局,避免页码和总页数被拆成两段
  • 当前 Mermaid 渲染默认写入保守的 Puppeteer 配置,规避 headless shell 在受限环境下失败
  • md2word.py 会在生成的 DOCX 中把 Markdown 标题映射回 Word Heading 样式和大纲级别
  • word_mht_pipeline.ps1 会把常见块公式环境归一化后再交给 Word BuildUp
  • 当前已覆盖这些块环境:
    • matrix
    • pmatrix
    • bmatrix
    • Bmatrix
    • vmatrix
    • Vmatrix
    • cases
  • 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、处理正文和 Mermaid
  • scripts/generate_template_mht.py:从模板规格生成可复用 MHT 模板
  • scripts/style_presets.py:统一加载样式预设配置
  • scripts/word_common.ps1:Word worker 共享的 COM 清理与路径 helper
  • scripts/word_template_to_mht.ps1:DOCX 模板归一化为 MHT
  • scripts/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 才错:问题在 Word BuildUp
  • 如果矩阵类公式再次出问题,先检查传给 Word 的线性格式是否已经被归一化成 \matrix{...} 族,而不是残留 \begin{...} / \end{...}

Sponsors

Details

Marketplace
cp-yu/md2word
Author
cp-yu
Category
Document Processing
License
MIT