---
name: md2word
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.2.0"
license: MIT
description: Markdown转Word文档技能。将Markdown文档转换为符合中文排版标准的专业格式Word文档，支持多种预设格式。适用于正式文档、论文、报告等需要规范排版的文档转换。
---

# Markdown转Word文档Skill

## 概述

将 Markdown 文档转换为符合中文排版标准的 Word 文档。支持完整的 Markdown 语法，自动应用专业格式设置。

## 依赖要求

### Python 依赖

```bash
pip install python-docx Pillow beautifulsoup4 PyYAML
```

### 可选依赖

```bash
npm install -g @mermaid-js/mermaid-cli   # Mermaid 图表渲染
brew install librsvg                       # SVG→PNG（推荐，rsvg-convert）
# 或 pip install cairosvg                  # SVG→PNG 备选
# 或 npm install puppeteer                 # SVG→PNG 备选（scripts/svg2png.js）
```

> 正文内联 `<svg>...</svg>` 块会自动渲染为 PNG 嵌入，渲染优先级 rsvg-convert → cairosvg → svg2png.js(puppeteer)，三者任一即可；全部不可用时降级为代码框显示 SVG 源码。

## 快速开始

主转换脚本：`scripts/md2word.py`

```bash
# 基本转换
python scripts/md2word.py input.md output.docx

# 使用预设格式
python scripts/md2word.py input.md --preset=academic

# 使用自定义配置
python scripts/md2word.py input.md --config=my-config.yaml

# 脚注/尾注模式（默认 footnote 页面脚注；endnote=文档末注释+上标编号）
python scripts/md2word.py input.md --notes=endnote

# 全书合并：多章 md → 单 docx（目录+章间分页+页眉，配合 -o 指定输出）
python scripts/md2word.py --book ch01.md ch02.md ch03.md -o book.docx --preset=book-publish
```

## 配置系统

### 内置预设

预设信息从 YAML 文件动态读取，运行以下命令查看完整列表：

```bash
python scripts/config.py --list
```

常用预设：

- **legal** — 法律文书格式（默认）
- **service-plan** — 法律服务方案（含分层配色）
- **minimal** — 极简格式
- **academic** — 学术论文格式
- **report** — 工作报告格式
- **book-publish** — 中文书籍出版格式（正文宋体、标题黑体、TOC/页眉书名，配合 `--book` 全书合并导出）

> 完整配置见 `assets/presets/*.yaml`，设计说明见 `assets/theme-notes/`

### 自定义配置

复制配置模板并修改：
```bash
cp assets/config-template.yaml my-config.yaml
```

### Word 模板文件

将 `.docx` 模板放入 `assets/templates/` 目录，或使用 `--template` 指定。

**Word 模板 vs 配置文件**：
- **Word 模板**：控制视觉元素（页眉、页脚、Logo）
- **配置文件**：控制格式参数（字号、行距、页边距）

## 参考文档

- **配置参考**: [references/config-reference.md](references/config-reference.md)
- **样式映射**: [references/style-mappings.md](references/style-mappings.md)
- **使用示例**: [references/examples.md](references/examples.md)

## 所需权限与安全说明

本技能会调用本地脚本执行文档转换，涉及以下能力边界，请在使用前知悉：

### 本地代码执行

- `scripts/md2word.py` 通过 `subprocess.run` 调用外部渲染工具渲染图表与 SVG：
  - **Mermaid 图表**：调用 `mmdc`（MMDCCMD 环境变量 → 脚本同目录 `node_modules/.bin/mmdc` → 系统 PATH），仅渲染用户输入的 mermaid 代码，命令以参数数组拼接，不经过 shell 字符串拼接。
  - **SVG 渲染**：按优先级调用 `rsvg-convert` → `cairosvg` → `node scripts/svg2png.js`（Puppeteer）。内联 SVG 为不可信输入时，可能触发渲染器解析问题或资源消耗，请只转换可信来源的文档。

### 网络访问（默认启用）

- 转换含外部 URL 图片的 Markdown 时会**自动向任意 HTTP/HTTPS 地址发起请求**（`urllib.request`，超时 20s），用于下载图片嵌入 Word。
- 这是**默认行为**：外链图片会正常下载并嵌入文档；下载失败时降级为文字占位符。
- 请知悉风险：处理不可信 Markdown 可能触发 **SSRF**（访问内网地址）、向第三方泄露转换方 IP/时间等元数据、引入恶意或超大图片负载。请仅转换可信来源的文档。
- 上述下载请求不会上传文档内容，只按 Markdown 中的图片 URL 拉取图片。

### 环境变量读取

- `chart_handler.py` 读取 `MMDCCMD` 环境变量以定位 mermaid-cli 可执行文件（可选，未设置时回退到脚本同目录 node_modules 与系统 PATH）。

### 文件访问

- 读取用户指定的 Markdown 输入文件、`assets/templates/` 下的 Word 模板与 `assets/presets/` 下的 YAML 配置。
- 在输出目录生成 Word 文档（`--book` 模式会生成临时合并 Markdown，转换结束后自动删除）。

## 错误处理

- **文件编码**：自动检测 UTF-8 和 GBK
- **模板找不到**：使用默认格式创建新文档
- **Mermaid 失败**：降级为文本描述
- **图片过大**：自动压缩和调整尺寸

## 目录结构

```
md2word/
├── SKILL.md               # 本文档
├── CHANGELOG.md           # 版本记录
├── references/            # 参考文档
│   ├── config-reference.md
│   ├── style-mappings.md
│   └── examples.md
├── scripts/               # 转换脚本
│   ├── md2word.py         # 主脚本
│   ├── config.py          # 配置模块（含 --list 查看预设）
│   ├── extract_template_config.py  # 从 Word 模板提取配置
│   ├── formatter.py       # 文本格式化模块
│   ├── table_handler.py   # 表格处理模块
│   └── chart_handler.py   # 图表渲染模块
└── assets/                # 资源文件
    ├── presets/           # YAML 预设配置
    ├── theme-notes/       # 预设设计说明文档
    ├── templates/         # Word 模板文件
    └── config-template.yaml
```