md-to-word

English | 简体中文 | 在线演示站 (Playground)

把 Markdown 确定性编译为出版级规范 Word（.docx）。专为学术期刊、技术报告、学位论文、公文打造，也是面向 AI Agent 设计的确定性排版与出版交付底座。

🌐 零门槛免安装试玩：点击访问官方在线体验站 (Web Playground)，实时编辑内容，在线验证公式、三线表、页眉与出版规范，秒级下载成品 .docx。

为什么需要 md-to-word？

大模型直接编写 python-docx 脚本极易产生格式漂移、表格断裂或样式幻觉；而通用工具（如 Pandoc）改动细节需深入修改复杂底模与后处理过滤器。

md-to-word 采用声明式排版契约与带精确行号的双向质量门禁：

• 逐字节一致：同一份源文件在任何操作系统重编译，产物二进制完全一致；

• 自愈门禁：格式没写全或语法错误，导出前精准指示行号并提供自愈指引，让 AI Agent 具备自主调试闭环能力；

• 出版级排版：原生 OMML 矢量数学公式（双击可编辑、自动居中、编号靠右）、跨页自动重复表头三线表、双线/单线页眉、中西文字体分离。

架构认知：自包含核心与多形态接入

💡 核心设计哲学： 本项目的底层是纯净、确定性的 Python 编译引擎（md-to-word-docx），内置了完整的排版契约规范与自检逻辑。为了解决“排版契约一旦升级、外部 Prompt/技能文档就失效不同步”的痛点，项目采用规范内置自包含设计（运行 md-to-word --guide 即可输出与最新代码 100% 同步的完整指南）。 无论你是想在网页上免安装试玩、在桌面端挂载为原生 AI 工具（MCP）、在智能体中作为技能（Skill）调用，还是在终端执行 CLI 批处理，底层运行的都是同一套严格对账的编译逻辑。

选型对比与使用全景

快速上手指南

1. 🤖 作为 MCP 原生外设使用（Claude Desktop / Cursor）

MCP（Model Context Protocol）是 Anthropic 开源的标准模型上下文协议。AI 客户端不需要运行在命令行中，直接通过标准协议将 md-to-word 当作专属排版外设调用。

为什么无需手动安装？
推荐使用现代 Python 工具链 uvx，它会在首次调用时自动从 PyPI 下载依赖并在隔离环境中执行，无需污染全局系统。

在你的 claude_desktop_config.json（或 Cursor MCP 配置）中添加：

{
  "mcpServers": {
    "md-to-word": {
      "command": "uvx",
      "args": ["--from", "md-to-word-docx[mcp]", "md-to-word-mcp"]
    }
  }
}

（注：若习惯本地全局 Python 环境，亦可运行 pip install "md-to-word-docx[mcp]"，并将 command 设为 python3，args 设为 ["-m", "md_to_word.mcp"]）

AI 自动获得的原生能力：

• compile_markdown：将输入的 Markdown（文本或文件路径）直接编译为出版级 .docx（并可按需转为 PDF）；

• validate_manuscript：在生成前执行预检，自动检测未闭合的数学公式、缺线的表格或格式错误；

• list_presets：按需选择中文核心期刊、白皮书或 Nature 顶级英文规范；

• inspect_preset：透明查阅任意预设的完整字体、行距与排版规则（format.txt）。

2. 🧠 作为 Agent Skill 技能使用（Claude Code / Nature 生态）

如果你在命令行或具备 Shell 权限的 Agent（如 Claude Code、OpenCode）中使用：

• 自动化一键挂载：

  npx skills add ls-open/md-to-word

• Nature Skills 生态内置： 本项目已正式合并入 Nature Skills (51k+ ★) 官方生态中，已安装环境直接输入 $nature-paper2word 即可唤起。

• 手动导入： 将仓库中的 SKILL.md 复制到你项目的技能目录（如 .claude/skills/）即可。

3. 💻 本地 pip 安装与命令行直接运行

如果你需要脱离大模型直接作为本地生产力工具使用：

# 安装核心编译器
pip install md-to-word-docx

# 初始化示例项目
md-to-word init

# 查看最新排版契约与编写指南（自包含内核）
md-to-word --guide

# 执行编译（支持指定预设或自定义 format.txt）
md-to-word 论文.md -p zh-academic -o 论文.docx

指定格式文件导出

md-to-word 稿件.md -r format.txt -o 稿件.docx

- **作为 Python 库调用**：
```python
from md_to_word import export

result = export("稿件.md", "稿件.docx", rules="format.txt")
if not result.ok:
    raise SystemExit("\n".join(result.errors))

Related MCP server: mcp-server-docx

样例展示

以下样例均由真实编译流程生成，页图由生成的 PDF 真实渲染，非效果图：

手上有现成的 Word 模板？

学校、期刊或单位下发的 .docx 模板不必逐条手工抄写。使用内置的模板反推器：

md-to-word-template 学校模板.docx -o format.txt

反推器会自动解析页面尺寸、页边距、页眉页脚距边界、页码样式与起始、各级样式的中西文字体、字号、加粗倾斜、行距（倍数/固定值）、段前段后、字符缩进、表格边框及表头行。未能完全判定的项会自动生成待确认清单，严谨可靠。

排版能力一览

• 页面与正文：纸张、页边距、装订线、文档网格、中西文字体、字号、行距、缩进、段距、对齐、颜色

• 标题与页眉页脚：六级标题、奇偶页与首页不同、分节、页码格式与起始、{页码} {总页数} {样式标题} 域

• 表格：三线表、全网格线、顶底线、无边框，线宽、跨页重复表头、单元格垂直水平对齐、列宽比例

• 公式：原生 OMML 公式对象（Word 内可直接双击二次编辑，绝非位图或文本伪造），居中、编号靠右、按章编号、@eq- 交叉引用

• 图与题注：图片宽度按版心智能钳制，题注与图同页绑定防掉页，直接支持矢量 PDF 插图（导出时自动 300 dpi 高清栅格化）

• 文献与引用：.bib + CSL 样式体系，内置 29 份常用期刊与国家标准样式（GB/T 7714、APA、Nature、IEEE 等），支持自定义 CSL

• 行内样式：加粗、斜体、删除线、下划线、上下标、行内代码、行内公式、超链接、脚注

• 结构标记：目录域 {{< toc >}}、分节换页码 {{< section >}}、分页 {{< pagebreak >}}

• 质量门禁：导前预检（契约、样式、引文合法性）、导后防丢数核对、逐条样式对账

• 纯 Python 本地导出：整条链路在 Python 进程内完成，无需额外安装或启动 Office/WPS/Pandoc

完整功能边界与词表详见使用手册。

常用写法契约速查

与其他方案的区别

协同生态与收录

本项目专注下游的高质量确定性排版与出版交付，前期的文献调研、开题构思与论文写作推荐配合以下学术 Agent 框架：

• Nature Skills（51k+ ★）：顶流科研论文全流程写作 Agent 技能集。本项目已作为官方内置独立技能 nature-paper2word 正式合并入官方仓库，负责该生态终稿阶段的“规范 Word 编译交付”。在 Nature Skills 环境中可直接唤起 $nature-paper2word。

• Academic Research Skills（51k+ ★）：五阶段学术研究全流程框架。本项目被收录在官方第三方项目列表中，在 Stage 5（FINALIZE）产出 Markdown 草稿与参考文献后，直接承接出规范 .docx。

• 中文独立开发者：收录于程序员专刊精选独立项目。

许可

代码开源遵循 MIT License。
内置引文样式来自 citation-style-language/styles（CC BY-SA 3.0）；内置底模由本项目生成，随 MIT 发布。