# markdown2word

**Repository Path**: oldlie/markdown2word

## Basic Information

- **Project Name**: markdown2word
- **Description**: 将 markdown 文档转换成 word
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# md2docx — Markdown 转 Word 文档工具

> 版本：1.0.0

## 概述

**md2docx** 是一个命令行工具，根据《规则.config》（TOML 格式）的样式配置，将《内容.md》转换为带自动版本号的 docx 文档。

适用于需要将技术文档、项目方案、需求文档等 Markdown 文稿输出为规范化 Word 文档的场景。

## 安装

### 环境要求

- Python 3.11+
- pip

### 安装依赖

```bash
cd md2docx
pip install -r requirements.txt
```

依赖列表：

- `python-docx>=1.1.0` — 生成 Word 文档
- `mistune>=3.0.0` — 解析 Markdown

## 快速开始

### 1. 准备输入文件

在 `md2docx/` 目录下创建两个文件：

- **规则.config**（TOML 格式）：定义输出配置、样式规则
- **内容.md**（Markdown 格式）：要转换的内容

### 2. 运行

```bash
python main.py
```

默认读取当前目录下的 `规则.config` 和 `内容.md`，输出到 `./output/` 目录。

### 3. 查看结果

```
md2docx/output/
└── 项目文档_v001.docx
```

每次运行自动递增版本号。第二次运行生成 `项目文档_v002.docx`，以此类推。

## 命令行参数

```bash
python main.py -c 规则.config -m 内容.md -o ./my_output --debug
```

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--config` | `-c` | 规则配置文件路径 | `规则.config` |
| `--content` | `-m` | Markdown 内容文件路径 | `内容.md` |
| `--output-dir` | `-o` | 输出目录（覆盖配置文件中的设置） | `./output` |
| `--debug` | | 打印 AST 调试信息 | false |
| `--version` | | 显示工具版本号 | |

## 《规则.config》配置说明

规则文件使用 **TOML** 格式，支持完整的注释。

### [output] — 输出设置

```toml
[output]
prefix = "项目文档"       # 文件名前缀
output_dir = "./output"  # 输出目录
version_digits = 3       # 版本号位数 → v001, v002, ...
```

### [page] — 页面设置

```toml
[page]
margin_top = 2.54      # 上边距（厘米）
margin_bottom = 2.54   # 下边距
margin_left = 3.17     # 左边距
margin_right = 3.17    # 右边距
```

标准 A4 页边距：上下 2.54cm，左右 3.17cm。

### [font] — 正文字体

```toml
[font]
family = "宋体"    # 字体名称
size = 12          # 字号（磅）
```

### [heading] — 标题字体

```toml
[heading]
family = "黑体"    # 标题字体
bold = true        # 是否加粗

[heading.sizes]
1 = 22     # h1 → 一号
2 = 18     # h2 → 小二
3 = 16     # h3 → 三号
4 = 14     # h4 → 四号
5 = 12     # h5 → 小四
6 = 10.5   # h6 → 五号
```

字号参考：

| 级别 | 字号名称 | 磅值 |
|------|----------|------|
| 一号 | 初号 | 42pt |
| 二号 | 小初 | 36pt |
| 三号 | 一号 | 26pt |
| 四号 | 小一 | 24pt |
| 五号 | 二号 | 22pt |
| 六号 | 小二 | 18pt |
| 七号 | 三号 | 16pt |
| 八号 | 四号 | 14pt |
| 九号 | 小四 | 12pt |
| 十号 | 五号 | 10.5pt |

### [table] — 表格样式

```toml
[table]
border = true                # 是否显示全边框
header_bold = true           # 表头是否加粗
header_fill_color = "D9E2F3" # 表头背景色（RGB 十六进制）
alternate_row = false        # 是否交替行颜色
alternate_fill_color = "F2F2F2"
```

### [code] — 代码块样式

```toml
[code]
family = "等线"          # 等宽字体
size = 9                 # 字号
background_color = "F5F5F5"  # 背景色
```

### [blockquote] — 引用块样式

```toml
[blockquote]
family = "楷体"           # 字体
size = 11                 # 字号
left_indent_cm = 0.75     # 左侧缩进（厘米）
```

### [link] — 超链接样式

```toml
[link]
color = "0563C1"     # 链接颜色
underline = true     # 是否加下划线
```

## 《内容.md》支持的 Markdown 语法

### 标题

```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
```

### 文本样式

```markdown
**粗体**
*斜体*
`行内代码`
```

### 列表

```markdown
- 无序列表项 1
- 无序列表项 2
  - 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2
```

### 表格

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A   | B   | C   |
| D   | E   | F   |
```

### 代码块

````markdown
```python
def hello():
    print("Hello, World!")
```
````

支持的语言标注：`python`、`java`、`sql`、`bash`、`text` 等。

### 引用块

```markdown
> 这是一段引用文字
> 支持多行
```

### 任务列表

```markdown
- [x] 已完成的任务
- [ ] 未完成的任务
```

### 图片

```markdown
![图片描述](./images/example.png)
```

支持本地图片路径，自动插入 Word 文档并居中显示。图片宽度超过 5.5 英寸时自动缩放。

### 超链接

```markdown
[显示文本](https://example.com)
```

### 水平线

```markdown
---
```

## 版本号管理

版本号自动递增机制：

1. 首次运行时，输出目录中无匹配文件，生成 `v001`
2. 后续运行时，扫描输出目录下所有 `{前缀}_v*.docx` 文件
3. 提取最高版本号，自动 +1
4. 版本号位数由 `version_digits` 控制（默认 3 位）

示例：

```
output/
├── 项目文档_v001.docx   # 第一次运行
├── 项目文档_v002.docx   # 第二次运行
└── 项目文档_v003.docx   # 第三次运行
```

## 完整示例

### 规则.config

```toml
[output]
prefix = "技术方案"
output_dir = "./output"
version_digits = 3

[page]
margin_top = 2.54
margin_bottom = 2.54
margin_left = 3.17
margin_right = 3.17

[font]
family = "宋体"
size = 12

[heading]
family = "黑体"
bold = true

[heading.sizes]
1 = 22
2 = 18
3 = 16
4 = 14
5 = 12
6 = 10.5

[table]
border = true
header_bold = true
header_fill_color = "D9E2F3"
alternate_row = false

[code]
family = "等线"
size = 9
background_color = "F5F5F5"

[blockquote]
family = "楷体"
size = 11
left_indent_cm = 0.75

[link]
color = "0563C1"
underline = true
```

### 内容.md

```markdown
# 技术方案文档

## 1. 项目背景

本项目旨在构建一个 **高性能** 的停车管理系统。

### 1.1 核心目标

- 支持 **高并发** 场景
- 实现 *弹性扩展*
- 确保数据安全

## 2. 技术选型

| 组件 | 技术 | 版本 |
|------|------|------|
| 后端 | Spring Boot | 3.5.x |
| 数据库 | MySQL | 8.0.x |
| 缓存 | Redis | 7.x |

## 3. 核心代码

```python
def greet(name):
    return f"Hello, {name}!"
```

> 注意：所有服务通过消息队列异步通信。

---

## 版本历史

- [x] v1.0.0 基础功能完成
- [ ] v2.0.0 AI 优化（计划中）
```

### 运行命令

```bash
python main.py -c 规则.config -m 内容.md
```

## 常见问题

### Q: 输出文件名中的中文显示为乱码？

确保你的终端使用 UTF-8 编码。在 Windows 上，运行 `chcp 65001` 切换到 UTF-8。

### Q: 如何修改默认字体？

编辑 `规则.config` 中的 `[font]` 和 `[heading]` 部分，修改 `family` 值为系统中已安装的字体名称。

### Q: 表格没有边框？

检查 `规则.config` 中 `[table]` 部分的 `border = true` 是否设置。

### Q: 生成的 docx 打开后字体不对？

确保配置文件中指定的字体（如"宋体"、"黑体"）已在系统中安装。Word 打开文档时会尝试使用配置的字体，如果不存在则回退到默认字体。

### Q: 版本号跳跃了？

版本号基于输出目录中已存在的文件计算。如果手动删除或添加了文件，版本号会相应调整。建议保留连续的文件序列。

## 技术架构

```
main.py
  │
  ├─ config_loader.py  ← 读取规则.config（TOML）
  │
  ├─ md_to_ast.py      ← mistune 解析内容.md → AST
  │
  ├─ ast_to_docx.py    ← 遍历 AST → python-docx 构建
  │
  ├─ version_manager.py ← 扫描输出目录，自增版本号
  │
  └─ 保存 {前缀}_v{版本号}.docx
```