# Markdown To Docx

> |

- **Type:** Skill
- **Install:** `agentstack add skill-bushuhui-skills-markdown-to-docx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bushuhui](https://agentstack.voostack.com/s/bushuhui)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bushuhui](https://github.com/bushuhui)
- **Source:** https://github.com/bushuhui/skills/tree/master/markdown-to-docx

## Install

```sh
agentstack add skill-bushuhui-skills-markdown-to-docx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# markdown-to-docx

将 Markdown 文件转换为 Word DOCX 文件，提供两种转换方式。

## 两种转换方式对比

| 维度 | 方式 A：直接转换 | 方式 B：模板转换 |
|------|----------------|----------------|
| **引擎** | pandoc | python-docx |
| **公式支持** | ✅ LaTeX → OMML | ❌ 纯文本（公式保留为 $...$） |
| **样式控制** | pandoc 默认样式 | ✅ 匹配参考模板样式 |
| **中文支持** | 取决于 pandoc 版本 | ✅ 完美（宋体/黑体等） |
| **适用场景** | 学术论文、含公式的技术文档 | 公文、技术方案、报告、需要匹配模板的文档 |
| **图片** | ✅ 支持 | ❌ 不支持 |

### 选择指南

- 用户要求"直接转"、"转一下" → **方式 A**
- 用户提供参考模板（"用这个当模板"） → **方式 B**
- 文档含大量 LaTeX 公式 → **方式 A**
- 需要匹配特定样式/字体/排版 → **方式 B**
- 用户两个都提了 → 两种方式都执行

---

## 方式 A：直接转换（pandoc）

使用 `md2docx.sh` 或 `md2docx_converter.py` 脚本。

### 快速命令

> 以下 `SKILL_DIR` 表示本 skill 所在的实际目录路径，执行时请替换为真实路径。

```bash
# Shell 脚本（推荐）
bash "${SKILL_DIR}/md2docx.sh"  [output.docx]

# Python 脚本（含公式修正）
python3 "${SKILL_DIR}/md2docx_converter.py"  [output.docx]
```

### 特点
- `--mathml`：LaTeX 公式转为 Word 原生 OMML 格式
- 自动修正公式格式问题（数字间空格、下标等）
- 支持行内 `$...$` 和块级 `$$...$$` 公式

---

## 方式 B：模板转换（python-docx）

使用参考模板的样式（字体、字号、加粗、Heading 级别等）来渲染 Markdown 内容。

### 快速命令

```bash
python3 "${SKILL_DIR}/md2docx_template.py"  --template  -o 
```

### Markdown 标题到 Word 样式的映射规则

| Markdown 元素 | 默认映射 | 特殊规则 |
|--------------|---------|---------|
| `# 标题`（第一个） | Normal（加粗黑体，作为文档标题） | 不转 Heading 1 |
| `## 研究内容、功能` / `## 主要性能指标` | Heading 1 | 根据关键词自动识别 |
| `## 1、xxx` / `## 2、xxx` 等 | Heading 2 | 编号型子标题 |
| 正文 | Normal（宋体 12pt） | |
| `1.` `2.` `3.` 开头的行 | Normal（独立段落） | 技术指标等编号列表 |

### 样式配置

```python
# 标题样式
title: 黑体, 16pt, bold
# Heading 1（大章节）
H1: 黑体, 16pt, bold
# Heading 2（子标题）
H2: 黑体, 14pt, bold
# 正文
Normal: 宋体, 12pt
```

### 完整流程

```python
from docx import Document
from docx.shared import Pt
from docx.oxml.ns import qn
import re

# 1. 加载模板
doc = Document(template_path)

# 2. 清空原有内容
for p in doc.paragraphs:
    p.clear()

# 3. 解析 Markdown
lines = md_content.strip().split('\n')
entries = []  # (style_id, text)

for line in lines:
    if line.startswith('## '):
        title = line[3:].strip()
        # 关键词识别大章节
        if title in ('研究内容、功能', '主要性能指标', '研究目标', '技术路线'):
            entries.append(('H1', title))
        else:
            entries.append(('H2', title))
    elif line.startswith('# '):
        entries.append(('Title', line[2:].strip()))
    elif re.match(r'^\d+\.', line):
        entries.append(('Normal', line))  # 编号行独立成段
    else:
        # 合并连续文本行
        ...

# 4. 逐段写入，匹配样式
for idx, (style_id, text) in enumerate(entries):
    p = doc.paragraphs[idx] if idx  len(entries):
    p = doc.paragraphs[-1]
    p._element.getparent().remove(p._element)

# 6. 保存
doc.save(output_path)
```

### 关键注意事项

1. **中文字体**：必须用 `run._element.rPr.rFonts.set(qn('w:eastAsia'), '宋体')` 设置东亚字体，否则 Word 可能用默认字体渲染中文
2. **编号段落独立成段**：技术指标等 `1.` `2.` `3.` 开头的行必须作为独立段落，不能合并
3. **标题识别**：第一个 `#` 行作为文档标题（Normal 样式 + 黑体加粗），不作为 Heading
4. **多余段落清理**：写入完成后必须删除模板中多余的段落，否则文档尾部会有空行
5. **公式处理**：模板转换不支持 LaTeX → OMML，公式保留为 `$...$` 文本

---

## 组合使用示例

### 场景：同时执行两种转换

```bash
# 方式 A：pandoc 直接转（保留公式）
bash md2docx.sh input.md output_pandoc.docx

# 方式 B：模板转换（匹配样式）
python3 md2docx_template.py input.md --template template.docx -o output_template.docx
```

### 场景：先用方式 B 转换，再检查公式显示

如果用户需要公式在 Word 中可编辑，推荐方式 A。如果用户更看重排版/样式匹配，推荐方式 B。

---

## 自动格式检查与修复（新增）

**在转换前自动运行 `md_fixer.py`**，检测并修复以下非标准 Markdown 格式：

| 修复项 | 修复前 | 修复后 |
|--------|--------|--------|
| HTML 表格 | `...` | `\| 列1 \| 列2 \|` |
| 非标准分隔行 | `\|\|-\|\|\|-\|` | `\|---\|---\|---\|` |
| 图片路径检查 | 引用不存在的路径 | ⚠ 警告报告 |

**使用方式**：直接调用 `md2docx.sh`，格式检查自动执行。

---

## 文件清单

| 文件 | 用途 |
|------|------|
| `md2docx.sh` | Shell 脚本 — 入口脚本（含自动格式检查） |
| `md_fixer.py` | Python 脚本 — Markdown 格式检查与修复器 |
| `md2docx_converter.py` | Python 脚本 — 含公式修正的 pandoc 转换 |
| `md2docx_template.py` | Python 脚本 — 模板样式匹配转换 |
| `skill.md` | 本文档 |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bushuhui](https://github.com/bushuhui)
- **Source:** [bushuhui/skills](https://github.com/bushuhui/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bushuhui-skills-markdown-to-docx
- Seller: https://agentstack.voostack.com/s/bushuhui
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.