md-to-word

Files (10)

• CHANGELOG.md
• README.md
• SKILL.md
• reference-cn-modern.docx · assets/
• reference-compact.docx · assets/
• reference-default.docx · assets/
• config.yaml
• build_reference_templates.py · scripts/
• fix_template_namespace.py · scripts/
• md_to_word.py · scripts/

SKILL.md (first lines)

# md-to-word（Markdown 转 Word）

## 目标

将一个或多个 Markdown 文档转换为格式优美的 Word（.docx），基于 Pandoc + 内置 reference.docx 模板（可选自定义模板），并确保不修改任何原始 Markdown 文件。内置模板已修复命名空间兼容性问题，支持 RGBA 图片自动转换。

## 流程

### 输入

输入为一个或多个 Markdown 文件；可选输入包括内置或自定义 `reference.docx`、输出目录、Pandoc 参数和图片处理选项。转换不得修改原始 Markdown，输出路径须在用户授权范围内。

### 执行步骤

#### 你要解决的问题

用户给你一个或多个标准 Markdown 文档，希望把它们转换成**排版美观、可审查、可交付**的 Word（`.docx`），并且能在不同项目里复用同一套转换流程与样式模板。

**常见问题解决方案**：
- **RGBA PNG 导致 Word 警告**：使用 `--fix-images` 自动转换为 RGB 模式
- **图片路径问题**：脚本自动处理相对路径资源引用
- **中文排版问题**：使用 `--template cn-modern` 获得更好的中文样式

#### 内置模板（Pandoc reference.docx）

内置模板文件位于 `assets/`：
- `default`：`assets/reference-default.docx`
- `cn-modern`：`assets/reference-cn-modern.docx`（中文更友好字体/样式）
- `compact`：`assets/reference-compact.docx`（更紧凑段落间距）

#### 推荐执行方式

优先运行确定性脚本 `scripts/md_to_word.py`，避免 AI 手写 Pandoc 命令导致参数缺失或误覆盖。

示例：

```bash
python3 md-to-word/scripts/md_to_word.py \
  --template cn-modern \
  --output-dir /path/to/out \
  /path/to/a.md /path/to/b.md
```

如用户需要自定义样式，允许：
- 使用 `--reference-doc /path/to/reference.docx` 覆盖内置模板（用户自带）。
- 需要用同一份 Markdown 生成多套风格时，使用 `--output-suffix` 避免覆盖（默认不覆盖）。
- 用户不确定模板可选项时，先运行 `python3 md-to-word/scripts/md_to_word.py --list-templates`。

#### 核心工作流

##### 步骤 0：预检查（不写任何输出前）

1. 校验 `md_files` 均存在且为文件。
   - 默认仅接受 `.md/.markdown`；如用户确实给了其他扩展名，必须显式使用 `--allow-any-extension`。
2. 确认 Pandoc 可用（默认执行 `pandoc --version`）；不可用时给出明确安装提示，并停止。
3. 选择模板：
   - 优先 `--reference-doc`（用户显式指定）；
   - 否则使用 `--template`（默认 `default`）。
4. 计算输出路径：
   - 默认：`{input_dir}/{basename}.docx`
   - 单输入且用户想指定输出文件名：使用 `--output /path/to/out.docx`
   - 指定 `--output-dir`：`{output_dir}/{basename}.docx`
   - 若输出已存在：默认报错并停止（除非用户明确要求 `--overwrite`）。

##### 步骤 1：逐文件转换（必须覆盖全部输入）

对每个 Markdown 文件：
- **图片处理**（可选，`--fix-images`）：
  - 在 MD 所在目录创建 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/md-to-word/{yyyy-mm-dd-hh-mm}/` 隐藏工作目录
  - 创建 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/md-to-word/{yyyy-mm-dd-hh-mm}/output/images-rgb/` 存放转换后的图片
  - 创建 MD 副本，更新所有图片链接指向 RGB 版本
  - 仅转换非 RGB 模式的图片（RGBA/P/L 等），RGB 图片直接复制
- 以**非 shell**方式调用 Pandoc（防止命令注入）。
- 自动设置 `--resource-path`，包含 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/md-to-word/{yyyy-mm-dd-hh-mm}/` 目录。
- 生成 `.docx` 到目标输出路径。
- 可选：使用 `--clean` 转换后清理 `.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/md-to-word/{yyyy-mm-dd-hh-mm}/` 工作目录（默认保留便于增量转换）

##### 步骤 2：轻量自检（输出后必须做）

- [ ] 输入 Markdown 文件的内容未被修改（可选：对关键输入做 hash 前后对比）
- [ ] 输出 `.docx` 均成功生成且路径符合预期
- [ ] 未发生意外覆盖（除非用户明确要求）
- [ ] 如存在图片/链接，Word 中渲染正常（无法验证时说明原因与建议）

### 输出

#### 输入输出

**输入**
- `md_files`：一个或多个 Markdown 文件路径（建议 `.md` / `.markdown`）
- 可选：`template`（内置模板名）或 `reference_doc`（自定义 reference.docx 路径）
- 可选：`output_dir`（输出目录）

**输出**
- 对每个输入 Markdown，生成一个同名 `.docx`（默认输出到输入文件同目录；也可输出到 `output_dir`）

### 输出管理

#### BenszAPI 任务工作区


### 校验

转换前检查输入扩展名、文件存在性、Pandoc/Pillow 可用性和模板；转换后核对每个 `.docx` 存在、可打开、图片/链接渲染正常（无法验证时明确说明），且源 Markdown 未被覆盖。

### 失败与恢复

#### Word 兼容性问题与解决方案

##### 问题 1：Word 打开时提示"发现无法读取的内容"（模板命名空间问题）

**原因**：自定义 Word 模板使用了非标准的 XML 命名空间前缀（`ns0:`），与 Pandoc 的 `--reference-doc` 参数结合时可能导致 Word 兼容性问题。

**解决方案**：
1. **内置模板已修复**：所有内置模板（`cn-modern`、`compact`、`default`）已更新为使用标准命名空间
2. **自动兼容性参数**：脚本自动添加 `--markdown-headings=atx` 参数提高兼容性
3. **自定义模板修复**：使用 `scripts/fix_template_namespace.py` 修复自定义模板

```bash

From huangwb8/skills, MIT.

More from huangwb8/skills