md-to-docx

Category: Docs & Knowledge | Uploader: pickle-an | Downloads: 0 | Version: v1.0（Latest）
将 Markdown 文件转换为格式化的 Word 文档。当用户想要将 .md 转换为 .docx、从 Markdown 创建 Word 文档或提及文档转换时调用此技能。
Changelog: Source: GitHub https://github.com/pickle-an/md-to-docx-skill
Directory Structure

Current level: tree/main/skill/
📄 create_preview.py 11.2 KB
📄 create_template.py 2.5 KB
📄 markdown_normalizer.py 20.5 KB
📄 md_to_docx.py 45.3 KB
📄 SKILL.md 16.8 KB
📄 template.docx 18.2 KB
📄 template_preview.docx 20.2 KB
📄 version_manager.py 7.7 KB
SKILL.md

---
name: "md-to-docx"
description: "将 Markdown 文件转换为格式化的 Word 文档。当用户想要将 .md 转换为 .docx、从 Markdown 创建 Word 文档或提及文档转换时调用此技能。"
---
# Markdown 转 Word 文档转换器

本技能将 Markdown 文件转换为专业格式的 Word 文档（.docx）。

## 何时调用

在以下情况下调用此技能：

- 用户想要将 Markdown 文件转换为 Word 文档
- 用户要求从 Markdown 内容创建 Word 文档
- 用户提及 `.md` 到 `.docx` 的转换
- 用户需要格式化的文档输出

## 处理流程

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   输入 MD 文件   │ ──▶ │  版本号管理处理  │ ──▶ │  格式规范化处理  │ ──▶ │   解析 MD 元素   │ ──▶ │  生成 Word 文档  │
└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
                                                      │
                                            ┌─────────┴─────────┐
                                            ▼                   ▼
                                      ┌───────────┐       ┌───────────┐
                                      │ 保存规范化 │       │ 应用模板   │
                                      │ 后的文件   │       │ 样式       │
                                      └───────────┘       └───────────┘
```

## 功能特性

### 1. 自动版本管理

技能自动管理输出文件的版本号：


| 场景           | 输入文件         | 输出文件                                        |
| -------------- | ---------------- | ----------------------------------------------- |
| 文件名无版本号 | `document.md`    | `document_V1.docx`、`document_V1_normalized.md` |
| 文件名含版本号 | `document_V3.md` | `document_V4.docx`、`document_V4_normalized.md` |
| 目录中已有 V1  | `document.md`    | `document_V2.docx`、`document_V2_normalized.md` |

**版本规则：**

- 如果输入文件名包含版本号（如 `_V3`），则从该版本号递增
- 如果文件名无版本号，则扫描目录中已有版本并递增
- 版本格式：`_V{n}`，其中 n 为整数（V1、V2、V3...）
- `.docx` 和 `_normalized.md` 文件使用相同的版本号

### 2. Markdown 格式规范化

转换前，技能会自动规范化 Markdown 格式问题：


| 问题类型         | 示例                  | 修复                 |
| ---------------- | --------------------- | -------------------- |
| 未闭合的代码块   | ` ```python` 无闭合   | 自动添加闭合` ``` `  |
| 标题后无空格     | `###标题`             | →`### 标题`         |
| 标题中的中文数字 | `## 一、核心原理`     | →`## 1. 核心原理`   |
| 标题中的中文数字 | `### (一)技术细节`    | →`### (1) 技术细节` |
| 无序列表无空格   | `-项目`               | →`- 项目`           |
| 有序列表无空格   | `1.项目`              | →`1. 项目`          |
| 分隔线变体       | `--` 或 `----`        | →`---`              |
| 不匹配的粗体标记 | `**只有开头`          | 移除无效标记         |
| 不匹配的斜体标记 | `*只有开头`           | 移除无效标记         |
| 缺少表格分隔行   | 表格无`|---|`         | 自动添加分隔行       |
| 表格列数不一致   | 行的列数不同          | 自动填充/截断        |
| 多个连续空行     | 3+ 个连续空行         | 压缩为 1 个          |
| 标题前缺少空行   | 文本直接在标题前      | 添加空行             |
| 有序列表间距     | 列表项之间的空行      | **保留**（不移除）   |
| 段落首行空格     | `   带首行空格的文本` | 移除首行空格         |
| 段落间空行       | 段落之间的单个空行    | **移除**（清理）     |

**中文数字转换：**
技能自动将标题中的中文数字序列转换为阿拉伯数字：

- 支持：一、二、三、四、五、六、七、八、九、十（至二十）
- 模式 1：`一、` → `1.`（中文标点）
- 模式 2：`(一)` → `(1)`（括号形式）
- 适用于所有标题级别（# ~ ######）

**有序列表间距：**
有序列表项之间的空行会被智能保留以保持文档可读性：

- 如果两个编号列表项之间存在空行，该空行将被保留
- 这允许列表项内容有更好的视觉分隔
- 示例：`1. 项目 1` →（空行）→ `2. 项目 2` 将保留间距

**空行管理：**
技能根据上下文智能管理空行：

- **移除**：普通段落之间的空行（清理以获得更好的格式）
- **保留**：特殊元素周围的空行（标题、列表、代码块、表格、分隔线）
- **保留**：缩进内容周围的空行（列表项详情、嵌套项）
- **压缩**：多个连续空行减少为单个

**段落首行空白：**
普通段落的首行空白会自动移除以防止 Word 中出现双重缩进：

- Word 文档自动为段落应用首行缩进
- Markdown 中的首行空格会造成视觉不一致
- 列表项缩进被保留（无序列表和有序列表）
- 代码块和引用块保留其格式

### 3. 支持的 Markdown 元素


| 元素      | 语法                | 支持程度 |
| --------- | ------------------- | -------- |
| 标题      | `# ~ ######`        | 完全支持 |
| 段落      | 纯文本              | 完全支持 |
| 粗体      | `**文本**`          | 完全支持 |
| 斜体      | `*文本*`            | 完全支持 |
| 粗体+斜体 | `***文本***`        | 完全支持 |
| 无序列表  | `- 项目` / `* 项目` | 完全支持 |
| 有序列表  | `1. 项目`           | 完全支持 |
| 表格      | `| 列 |`            | 完全支持 |
| 代码块    | ` ```代码``` `      | 完全支持 |
| 行内代码  | `` `代码` ``        | 完全支持 |
| 链接      | `[文本](url)`       | 完全支持 |
| 图片      | `![替代文本](路径)` | 完全支持 |
| 引用块    | `> 引用`            | 完全支持 |
| 分隔线    | `---`               | 完全支持 |
| 删除线    | `~~文本~~`          | 完全支持 |
| 换行      | `<br>` 或 `\\`      | 完全支持 |

### 4. 文档格式规范

#### 字体规范


| 元素类型 | 中文字体 | 英文字体        | 字号         | 说明         |
| -------- | -------- | --------------- | ------------ | ------------ |
| 正文     | 宋体     | Times New Roman | 12pt（小四） | 标准正文字号 |
| 一级标题 | 宋体     | Times New Roman | 22pt（二号） | 大标题       |
| 二级标题 | 宋体     | Times New Roman | 16pt（三号） | 章节标题     |
| 三级标题 | 宋体     | Times New Roman | 15pt（小三） | 小节标题     |
| 四级标题 | 宋体     | Times New Roman | 14pt（四号） | 条目标题     |
| 五级标题 | 宋体     | Times New Roman | 14pt（四号） | 子条目标题   |
| 代码块   | Consolas | Consolas        | 9pt（小五）  | 略小于正文   |
| 行内代码 | Consolas | Consolas        | 12pt（小四） | 与正文同字号 |

#### 段落规范


| 属性     | 设置值 | 说明           |
| -------- | ------ | -------------- |
| 首行缩进 | 0.74cm | 约两个汉字宽度 |
| 行间距   | 1.5 倍 | 提升阅读舒适度 |
| 段前间距 | 0pt    | 保持紧凑排版   |
| 段后间距 | 0pt    | 保持紧凑排版   |

#### 标题规范


| 标题级别 | Markdown 语法 | 字号         | 样式特点                 |
| -------- | ------------- | ------------ | ------------------------ |
| 文档标题 | `# 标题`      | 22pt（二号） | 加粗、居中、可生成封面页 |
| 一级标题 | `## 标题`     | 22pt（二号） | 加粗、段前自动分页       |
| 二级标题 | `### 标题`    | 16pt（三号） | 加粗、不分页             |
| 三级标题 | `#### 标题`   | 15pt（小三） | 加粗、不分页             |
| 四级标题 | `##### 标题`  | 14pt（四号） | 加粗、不分页             |
| 五级标题 | `###### 标题` | 14pt（四号） | 加粗、不分页             |

#### 表格规范


| 属性       | 设置值     | 说明               |
| ---------- | ---------- | ------------------ |
| 表格样式   | Table Grid | 带边框的标准表格   |
| 对齐方式   | 居中       | 表格整体居中显示   |
| 列宽       | 自动计算   | 根据内容智能分配   |
| 表头背景   | #D9D9D9    | 浅灰色背景突出表头 |
| 表头对齐   | 居中       | 表头文字居中对齐   |
| 单元格对齐 | 左对齐     | 数据内容左对齐     |

#### 代码块规范


| 属性     | 设置值   | 说明               |
| -------- | -------- | ------------------ |
| 字体     | Consolas | 等宽字体，代码清晰 |
| 字号     | 9pt      | 略小于正文         |
| 背景色   | #F5F5F5  | 浅灰色背景区分代码 |
| 左缩进   | 0.5cm    | 突出代码块层次     |
| 语言标签 | 斜体显示 | 如`[python]`       |

#### 行内代码规范


| 属性   | 设置值   | 说明             |
| ------ | -------- | ---------------- |
| 字体   | Consolas | 等宽字体         |
| 字号   | 同正文   | 保持行高一致     |
| 背景色 | #F0F0F0  | 浅灰背景突出显示 |

#### 引用块规范


| 属性     | 设置值  | 说明         |
| -------- | ------- | ------------ |
| 左边框   | #6366F1 | 紫色竖线标识 |
| 边框宽度 | 1.5pt   | 清晰可见     |
| 左右缩进 | 1cm     | 突出引用内容 |
| 字体样式 | 斜体    | 区分引用文字 |

#### 列表规范


| 属性         | 设置值         | 说明             |
| ------------ | -------------- | ---------------- |
| 左缩进       | 0.74cm × 层级 | 支持多级嵌套缩进 |
| 行间距       | 1.5 倍         | 与正文保持一致   |
| 无序列表符号 | •             | 实心圆点         |
| 有序列表格式 | 1. 2. 3.       | 数字加点         |

#### 分隔线规范


| 属性         | 设置值   | 说明           |
| ------------ | -------- | -------------- |
| 样式         | 底部边框 | 段落下方的横线 |
| 颜色         | #CCCCCC  | 浅灰色         |
| 段前段后间距 | 6pt      | 保持适当间隔   |

#### 封面页规范


| 元素     | 设置值     | 说明                           |
| -------- | ---------- | ------------------------------ |
| 标题字号 | 22pt       | 与一级标题一致                 |
| 标题样式 | 加粗、居中 | 突出文档标题                   |
| 版本信息 | 12pt、居中 | 格式：版本：V1                 |
| 日期信息 | 12pt、居中 | 格式：编制日期：2024年01月01日 |
| 前置空行 | 3 行       | 标题上方留白                   |
| 后置空行 | 14 行      | 标题与版本信息间距             |

#### 分页控制


| 规则           | 说明                     |
| -------------- | ------------------------ |
| 一级标题前分页 | 每个一级标题自动另起一页 |
| 其他标题不分页 | 二级及以下标题保持连续   |
| 封面页后分页   | 封面页结束后自动分页     |

## 使用方法

### 基本转换

```
将此 Markdown 文件转换为 Word：
[提供 .md 文件路径或内容]
```

### 使用自定义模板

```
使用此模板将 Markdown 转换为 Word：
Markdown：[路径或内容]
模板：[.docx 模板路径]
```

### 带封面页

```
转换为带封面页的 Word：
[Markdown 内容]
标题：[文档标题]
版本：[版本号]
日期：[日期]
```

## 参数说明


| 参数               | 类型   | 必填 | 描述                                 |
| ------------------ | ------ | ---- | ------------------------------------ |
| `markdown_content` | 字符串 | 是   | Markdown 文本或文件路径              |
| `output_path`      | 字符串 | 否   | 输出 .docx 文件路径                  |
| `template_path`    | 字符串 | 否   | 自定义 .docx 模板路径                |
| `version`          | 字符串 | 否   | 封面页版本号（未提供则自动生成）     |
| `date`             | 字符串 | 否   | 封面页日期                           |
| `normalize`        | 布尔值 | 否   | 启用格式规范化（默认：true）         |
| `save_normalized`  | 布尔值 | 否   | 保存规范化后的 MD 文件（默认：true） |
| `use_versioning`   | 布尔值 | 否   | 启用自动版本编号（默认：true）       |

## 实现原理

技能使用 Python 脚本，逻辑如下：

### 步骤 0：版本管理（`version_manager.py`）

```python
# 自动确定输出文件的版本号
version_info = get_versioned_output_paths(input_path, output_dir)
# 返回：{ 'version': 1, 'docx_path': 'document_V1.docx', 'normalized_md_path': 'document_V1_normalized.md' }
```

### 步骤 1：格式规范化（`markdown_normalizer.py`）

```python
# 自动修复常见的 Markdown 格式问题
normalizer = MarkdownNormalizer()
normalized_content = normalizer.normalize(content)
# 保存到：original_filename_normalized.md
```

### 步骤 2：解析 Markdown（`md_to_docx.py`）

```python
# 将规范化的 Markdown 转换为结构化元素
parser = MarkdownParser()
elements = parser.parse(normalized_content)
```

### 步骤 3：生成 Word 文档

```python
# 创建带格式的 Word 文档
generator = DocxGenerator(template_path)
generator.create_document(output_path)
generator.generate(elements, version, date)
generator.save(output_path)
```

## 输出文件

转换后，生成以下文件：


| 文件                          | 描述                      |
| ----------------------------- | ------------------------- |
| `document_V{n}.docx`          | 带版本号的最终 Word 文档  |
| `document_V{n}_normalized.md` | 带版本号的规范化 Markdown |

**版本号示例：**

- 首次转换：`document_V1.docx`、`document_V1_normalized.md`
- 第二次转换：`document_V2.docx`、`document_V2_normalized.md`
- 带版本输入：`document_V3.md` → `document_V4.docx`

## 模板支持

### 使用自定义模板

如果提供了模板：

- 继承页面设置（边距、纸张大小）
- 继承样式定义（标题 1-6、正文）
- 添加新内容前清除模板内容

### 内置样式（无模板）

**本 Skill 可独立运行，无需外部模板文件。**

如果未提供模板或模板文件不存在：

- 自动创建空白文档
- 使用默认页面设置（A4，2.54cm 边距）
- 以编程方式创建样式
- 应用一致的格式

这意味着本 Skill 可以在任何安装了 Python 和 python-docx 的环境中独立运行，无需依赖外部模板文件。

## 示例

### 示例 1：格式规范化

**输入（含问题）：**

```markdown
# 测试文档
## 一、表格测试
| 列1|列2|列3
|数据1|数据2|数据3
###标题无空格
-项目1无空格
```

**规范化输出：**

```markdown
# 测试文档

## 一、表格测试

|列1|列2|列3|
|---|---|---|
|数据1|数据2|数据3|

### 标题无空格

- 项目1无空格
```

### 示例 2：简单转换

输入：

```markdown
# 项目文档

## 概述
这是项目概述。

## 功能特性
- 功能 1
- 功能 2
```

输出：格式化的 Word 文档，具有正确的标题层级和项目符号列表。

### 示例 3：带表格

输入：

```markdown
## API 端点

| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | /api/users | 获取所有用户 |
| POST | /api/users | 创建用户 |
```

输出：带格式化表格的 Word 文档，表头行为灰色背景。

### 示例 4：带代码块

输入：

```markdown
## 安装

```bash
npm install package-name
```

```

输出：带等宽字体代码块的 Word 文档。

## 错误处理

- **无效 Markdown**：记录警告，继续部分解析
- **模板缺失**：回退到内置样式
- **文件未找到**：返回清晰的错误消息
- **权限错误**：建议替代输出路径
- **格式问题**：在规范化阶段自动修复

## 依赖

- Python 3.x
- python-docx 库

## 模块文件

| 文件 | 描述 |
|------|------|
| `md_to_docx.py` | 主转换脚本 |
| `markdown_normalizer.py` | Markdown 格式规范化 |
| `version_manager.py` | 自动版本编号 |
| `create_template.py` | 模板生成脚本（可选） |
| `template.docx` | 默认 Word 模板（可选） |

**说明：**
- `template.docx` 是可选的模板文件，如果存在则使用，不存在则自动创建空白文档
- `create_template.py` 可用于重新生成符合格式规范的模板文件
- 本 Skill 可完全独立运行，无需外部依赖
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
md-to-docx

Directory Structure

SKILL.md

Report

Notice
