用途
md-to-docx 用于将 Markdown 文件转换为格式规范的 Word 文档（.docx），底层依赖 pandoc。它面向需要把 Markdown 内容输出为 Word 文档的场景，尤其是中文文档，默认提供符合中文排版习惯的模板。
主要能力
- 标题与文本格式：支持 H1–H6 标题、加粗、斜体、删除线。
- 列表：支持有序列表、无序列表以及嵌套列表。
- 表格：支持带格式的表格。
- 图片：自动嵌入图片。
- 链接与引用：支持链接和引用。
- 代码：支持代码块与行内代码。
- 中文标点保留：保留 。，""（）；！？ 等中文标点。
- 引用上标：自动将引用编号转换为上标格式，例如 文献1。→ 文献¹。，适用于学术文档。
- 默认中文模板：所有中文文本（正文、标题、副标题）使用仿宋字体，英文使用 Times New Roman，全部文字为黑色，1.5 倍行距，首行缩进两字符（24pt，精确对齐），标题后间距 1 行（12pt），标题不使用斜体。
使用方式
使用前需在环境中安装依赖：
- pandoc（必需）：
- macOS：
brew install pandoc - Linux（Debian/Ubuntu）：
sudo apt-get install pandoc - Windows：
choco install pandoc
- macOS：
- python-docx（创建模板所需）：
pip install python-docx
验证 pandoc 安装：pandoc --version
转换流程：
- 运行
pandoc --version检查 pandoc 是否已安装；若未安装，按上述方式安装。 - 确定输入与输出文件；若用户未指定输出文件名，需询问确认，并建议使用有意义的名称（如输入 report.md，建议输出 report.docx）。
- 使用 Bash 工具运行转换脚本：
python .claude/skills/md-to-docx/convert_md_to_docx.py input.md output.docx - 按需添加选项：
--toc：生成目录（默认不生成目录）--no-chinese-template：不使用仿宋字体模板--no-superscript-citations：禁用引用编号自动上标转换--reference-doc template.docx：使用自定义样式模板--title、--author、--date：设置文档元数据
- 批量转换：
python .claude/skills/md-to-docx/convert_md_to_docx.py --batch input_dir/ output_dir/ - 验证转换成功，并告知用户输出位置。
默认行为：除非指定 --no-chinese-template，脚本会自动使用仿宋中文字体模板。
示例：
- 单文件转换（使用默认中文模板）：
python .claude/skills/md-to-docx/convert_md_to_docx.py "教育改革方案.md" "教育改革方案.docx" - 带目录转换（可选，默认无目录）：
python .claude/skills/md-to-docx/convert_md_to_docx.py report.md report.docx --toc - 带元数据转换：
python .claude/skills/md-to-docx/convert_md_to_docx.py paper.md paper.docx --title "研究报告" --author "张三" --date "2025-11-20" - 批量转换：
python .claude/skills/md-to-docx/convert_md_to_docx.py --batch ./markdown_files/ ./word_docs/ - 使用自定义模板：
python .claude/skills/md-to-docx/convert_md_to_docx.py doc.md doc.docx --reference-doc company_template.docx
命令行选项参考：
input.md：输入 Markdown 文件路径output.docx：输出 Word 文档路径--toc：生成目录（默认不生成）--no-chinese-template：不使用默认中文字体模板--no-superscript-citations：不将引用编号转换为上标--reference-doc FILE：使用自定义 Word 模板设置样式--title TEXT：设置文档标题元数据--author TEXT：设置文档作者元数据--date TEXT：设置文档日期元数据--batch：启用批量转换模式--pattern PATTERN：批量模式的文件匹配模式（默认*.md）
适用场景
- 将中文 Markdown 文档转换为符合中文排版规范的 Word 文档。
- 学术文档转换，需要引用编号自动上标。
- 批量将目录下的 Markdown 文件转换为 Word 文档。
- 需要使用组织自定义 Word 模板统一风格的场景。
限制与注意事项
- 依赖 pandoc 与 python-docx，使用前必须安装。
- 图片不显示时，需检查 Markdown 中的图片路径是否正确（建议使用相对于 Markdown 文件位置的相对路径），并确认图片文件存在。
- 表格格式问题需检查 Markdown 表格语法是否正确。
- 脚本执行错误时，需确保脚本有执行权限（
chmod +x convert_md_to_docx.py），并在所有文件路径中使用正斜杠（Unix 风格）。 - 中文文档建议：Markdown 文件使用 UTF-8 编码；使用规范中文标点；默认模板对中文文本使用仿宋、黑色、1.5 倍行距、首行缩进两字符、标题后 1 行间距、标题不加斜体。
- 引用上标仅转换直接跟在中文或字母后、且位于句末标点（。；）之前的 1–60 的数字。
- 默认不生成目录，需通过
--toc添加。
附带文件
- README.md：详细使用指南与示例
- 快速使用指南.md：中文快速入门指南
- convert_md_to_docx.py：主转换脚本，含自动后处理
- create_chinese_template.py：创建自定义中文模板的工具
- fix_heading_fonts.py：字体与间距修复的后处理脚本
- chinese_template.docx：默认中文字体模板（仿宋、1.5 倍行距、标题间距）