前言¶

技术文档、方案稿、周报往往先在 Markdown 里写：版本好管、协作方便。交付给非技术同事或要走公司模板时，又需要 .docx。手工复制粘贴会丢标题层级、表格样式，本地图片也容易变成断链。

用 Pandoc 可以完成基础转换，但图片路径校验、题注样式（居中、字号）通常还要自己写脚本或事后在 Word 里改。下面介绍 SkillHub 社区 Skill md-to-docx-with-images：在 Agent 里按固定流程调用自带脚本，完成「检查环境 → 校验图片 → 转 docx → 修正题注」。

这是什么¶

md-to-docx-with-images（坐标 @user_29e2fa9e/md-to-docx-with-images，版本 1.0.0）由社区发布者 user_29e2fa9e 维护，分类为 office-efficiency，来源标注为 community。SkillHub 页面显示无需 API Key（requires_api_key=false）。

一句话定位：将 Markdown（.md）转为 Word（.docx），嵌入图片，保留标题样式与表格，并支持用参考模板 docx 统一版式；本机缺少 Pandoc 时可尝试自动安装。

官方入口：

• API / 资料页：https://api.skillhub.cn/user_29e2fa9e/md-to-docx-with-images
• SkillHub 展示页：https://www.skillhub.cn/skills/user_29e2fa9e/md-to-docx-with-images

核心功能¶

以下能力均来自该 Skill 的 SKILL.md 与配套脚本说明。

1. Markdown → DOCX：基于 Pandoc 转换，保留标题、表格以及粗体/斜体等常见格式。
2. 图片嵌入：处理 ![alt](path) 引用；路径相对于 Markdown 文件解析，也支持 Pandoc 可识别的远程 URL。
3. 参考文档样式：可通过 --reference-doc=template.docx 沿用已有 Word 的标题、表格、页边距等样式。
4. 转换前检查：check_images.py 在转换前确认图片文件是否存在，避免 Pandoc 因断链直接失败。
5. 题注后处理：md_to_docx.py 在转换后自动调整图片题注（居中、8pt、非斜体）；也可对已有 docx 单独运行 fix_captions.py。
6. Pandoc 自动安装：install_pandoc.py 在 Windows / macOS / Linux 上尝试安装 Pandoc；安装后需提醒用户必要时重启终端以刷新 PATH。

Skill 明确要求：优先使用 scripts/ 目录下的脚本，不要临时写内联转换代码。

依赖：Pandoc（必需）、Python（运行辅助脚本）；校验输出结构时文档中还用到 python-docx。

安装与启用¶

安装 SkillHub CLI（若尚未安装）¶

command -v skillhub && skillhub --version

未安装时可按 SkillHub 安装文档执行完整安装：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装本 Skill¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。

skillhub install md-to-docx-with-images --namespace user_29e2fa9e --dir <你的 Agent skills 目录>

常见 skills 目录（以 SkillHub 安装文档为准）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

也可以在对话里让 AI 按官方说明安装：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_29e2fa9e/md-to-docx-with-images`。

安装完成后，Skill 目录内包含 SKILL.md 与 scripts/（install_pandoc.py、check_images.py、md_to_docx.py、fix_captions.py）。在 Agent 中启用后，当用户提出「把某 md 转成 Word」「图片要进 docx」等需求时，Agent 应走文档中的工作流。

典型用法¶

以下命令均在 Skill 根目录下执行（即与 SKILL.md 同级），路径按你的实际文件替换。

1. 确认 Pandoc

pandoc --version

若未找到，先执行：

py scripts/install_pandoc.py

安装成功后按 Skill 要求告知用户：可能需要重启终端后 pandoc --version 才可用；自动安装失败则引导用户从 Pandoc 发布页 或系统包管理器手动安装。

2. 校验 Markdown 中的图片路径

py scripts/check_images.py input.md

3. 转换（推荐：脚本一条龙）

py scripts/md_to_docx.py input.md output.docx

需要沿用公司模板时，脚本第三个参数可传参考 docx（见 md_to_docx.py 命令行）；或直接用 Pandoc：

pandoc input.md -o output.docx --reference-doc=template.docx

若只用 Pandoc、未走 md_to_docx.py，转换后可单独修正题注：

py scripts/fix_captions.py output.docx

4. 可选：题注 alt 文本预处理

若 alt 写成 ![image2.png](...) 这类带扩展名的形式，Pandoc 可能把完整文件名当作题注；Skill 文档给出了用正则替换 alt 的 Python 片段，可在转换前处理 input.md。

5. 验证嵌入结果

可用 Skill 文档中的 zipfile 片段统计 word/media/ 下文件数，或用 python-docx 查看标题数、表格数。

推荐的目录结构示例：

project/
├── input.md
├── output.docx
└── img/
    ├── image1.png
    └── image2.jpeg

适用场景与注意¶

适合谁

• 经常在 Cursor、Claude Code、Codex 等环境里写 Markdown，又要交付 Word 的开发者或文档作者。
• 文档含较多 ./img/ 相对路径图片，希望 Agent 按同一套步骤转换，而不是每次重写 Pandoc 命令。
• 需要 --reference-doc 对齐企业 Word 模板样式。

限制与注意

• 必须有 Pandoc；Skill 写明没有能同等处理图片的纯 Python 回退方案。
• docx → md → docx 往返：复杂表格（合并单元格、嵌套表）可能在第一次转 Markdown 时丢失结构；简单 Markdown 表格在再转 docx 时仍可正确生成。
• 图片路径建议使用相对路径（如 ./img/）；断链会在 Pandoc 阶段报错，故应先跑 check_images.py。
• Windows 上运行脚本建议用 py scripts/...，避免 PowerShell 转义问题。
• .emf 等格式可嵌入，但在非 Windows 环境可能无法正常显示。
• 未提供 --reference-doc 时，输出使用 Pandoc 默认样式。

SkillHub 统计（抓取时）：评分 100000，下载 816，安装 51；具体数字以 SkillHub 页面为准。

结尾¶

md-to-docx-with-images 把 Markdown 转 Word 的常见步骤固化成 Skill：Pandoc 转换、图片校验、题注修正和可选参考模板，都适合交给 Agent 按文档执行。若你正在 SkillHub 上找办公效率类能力，可从官方页查看说明并安装：

https://www.skillhub.cn/skills/user_29e2fa9e/md-to-docx-with-images