# Markdown 转 DOCX 批量转换工具

## 功能说明

`convert_md_to_docx.py` 是一个用于批量将 Markdown 文件转换为 DOCX 格式的 Python 脚本。

## 依赖要求

- Python 3.6+
- pandoc（需要安装在系统中）

### 安装 pandoc

**Windows:**
```bash
# 使用 Chocolatey
choco install pandoc

# 或者下载安装包
# https://pandoc.org/installing.html
```

**macOS:**
```bash
brew install pandoc
```

**Linux:**
```bash
# Ubuntu/Debian
sudo apt-get install pandoc

# Fedora
sudo dnf install pandoc
```

## 使用方法

### 基本用法

```bash
# 转换指定目录下所有 .md 文件（递归）
python scripts/convert_md_to_docx.py docs/tutorial
```

### 常用参数

```bash
# 只转换当前目录的 .md 文件（不递归）
python scripts/convert_md_to_docx.py docs/tutorial --no-recursive

# 覆盖已存在的 .docx 文件
python scripts/convert_md_to_docx.py docs/tutorial --overwrite

# 指定输出目录
python scripts/convert_md_to_docx.py docs/tutorial --output output/docx

# 查看将要转换的文件（不实际执行）
python scripts/convert_md_to_docx.py docs/tutorial --dry-run

# 显示详细信息
python scripts/convert_md_to_docx.py docs/tutorial --verbose

# 只转换单个文件
python scripts/convert_md_to_docx.py docs/tutorial/1.员工入职欢迎信/template_welcome.md
```

### 高级用法

```bash
# 传递额外的 pandoc 参数（生成目录）
python scripts/convert_md_to_docx.py docs/tutorial --pandoc-args "--toc --toc-depth=2"

# 组合多个参数
python scripts/convert_md_to_docx.py docs/tutorial \
  --overwrite \
  --verbose \
  --output output/docx \
  --pandoc-args "--toc"
```

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `path` | 要转换的目录或文件路径（必需） | - |
| `-r, --recursive` | 递归搜索子目录 | True |
| `--no-recursive` | 不递归搜索子目录 | - |
| `-o, --output` | 输出目录 | 与源文件同目录 |
| `-f, --overwrite` | 覆盖已存在的文件 | False |
| `--pandoc-args` | 传递给 pandoc 的额外参数 | "" |
| `-v, --verbose` | 显示详细信息 | False |
| `--dry-run` | 仅显示将要转换的文件，不实际执行 | False |

## 注意事项

1. **$符号处理**: 脚本默认使用 `--from=markdown-tex_math_dollars` 参数，禁用数学公式解析，避免 `$` 符号被错误处理

2. **文件覆盖**: 默认情况下不会覆盖已存在的 .docx 文件，使用 `--overwrite` 参数强制覆盖

3. **输出目录**: 如果指定了输出目录，会自动创建不存在的目录

4. **错误处理**: 如果某个文件转换失败，会继续处理其他文件，并在最后显示统计信息

## 示例输出

```
找到 15 个 Markdown 文件

转换中: docs\tutorial\1.员工入职欢迎信\template_welcome.md -> docs\tutorial\1.员工入职欢迎信\template_welcome.docx
成功: docs\tutorial\1.员工入职欢迎信\template_welcome.docx

转换中: docs\tutorial\2.周报生成\template_weekly_report.md -> docs\tutorial\2.周报生成\template_weekly_report.docx
成功: docs\tutorial\2.周报生成\template_weekly_report.docx

...

转换完成!
  成功: 15
  失败: 0
  总计: 15
```

## 故障排查

### 找不到 pandoc 命令

**错误信息:**
```
错误: 未找到 pandoc 命令，请确保已安装 pandoc
```

**解决方法:**
1. 确认已安装 pandoc: `pandoc --version`
2. 如果未安装，参考上面的安装说明
3. 如果已安装但仍报错，确保 pandoc 在系统 PATH 中

### 转换失败

**常见原因:**
1. Markdown 语法错误
2. 文件编码问题（确保文件是 UTF-8 编码）
3. 路径包含特殊字符

**调试方法:**
```bash
# 使用 verbose 模式查看详细信息
python scripts/convert_md_to_docx.py docs/tutorial --verbose

# 单独转换失败的文件
python scripts/convert_md_to_docx.py path/to/failed/file.md
```

## 在项目中的典型工作流

```bash
# 1. 修改 markdown 模板
vim docs/tutorial/1.员工入职欢迎信/template_welcome.md

# 2. 批量转换所有模板
python scripts/convert_md_to_docx.py docs/tutorial --overwrite

# 3. 检查生成的 docx 文件
ls -la docs/tutorial/**/*.docx
```