DOCX 转 Markdown（含图片支持）

将 Word（.docx）文档转换为 Markdown，支持图片正确提取、内联格式保留以及相对路径引用。同时通过回退机制支持其他文档格式。

适用场景

• 用户要求将 .docx 文件转换为 .md / markdown 格式
• 用户希望保留文档中的图片
• 用户需要高保真转换，包括标题、表格、列表及各类格式化内容

前提条件

• pandoc（主用方案，必需用于高质量 .docx 转换并提取图片）
• python 及 python-docx 包（当 pandoc 不可用时的回退方案）
• uvx markitdown（用于其他格式的回退方案：PDF、PPTX、XLSX、HTML、CSV、JSON、XML）

脚本说明

所有脚本均位于相对于本技能文件的 scripts/ 目录下。请始终使用这些脚本，切勿编写内联代码。

DOCX 转换工作流

步骤 1：检查 pandoc 是否已安装

pandoc --version

步骤 1b：若缺失则自动安装 pandoc

若未找到 pandoc，请运行安装脚本，并向用户显示显著提示信息：

py scripts/install_pandoc.py

安装完成后，请验证：

pandoc --version

重要提示：成功安装 pandoc 后，必须明确告知用户：

“pandoc 已自动安装。您可能需要重启终端以使 PATH 更改生效。如果执行 pandoc --version 仍失败，请重启终端后重试。”

若自动安装失败，请显示以下消息：

“无法自动安装 pandoc，请手动安装：

• Windows：从 https://github.com/jgm/pandoc/releases/latest 下载安装包
• macOS：brew install pandoc
• Linux：sudo apt install pandoc”

步骤 2：使用 pandoc 提取图片并完成转换

# 创建 img 目录
mkdir -p ./img

# 执行转换并提取媒体文件
pandoc input.docx --extract-media="./img" -o output.md -f docx -t gfm

步骤 3：整理提取的图片并修正路径

运行内置脚本 —— 该脚本可同时完成目录扁平化与路径修正：

py scripts/fix_images.py output.md

该脚本执行以下操作：

1. 将 ./img/media/ 目录结构扁平化为 ./img/
2. 将 HTML 格式的 标签转换为标准 Markdown 格式 ![](./img/...)
3. 将绝对路径替换为相对路径
4. 移除图片周围的冗余

   标签及 style 属性

步骤 4：验证结果

# 应仅显示 ./img/ 开头的路径
grep -oP '![.*?](.*?)' output.md

# 应返回 0（表示无残留的  标签）
grep -c '
回退方案：python-docx（当 pandoc 不可用时）
当 pandoc 无法安装时，可使用内置的 python-docx 脚本：
py scripts/docx_to_md.py input.docx output.md

该脚本支持：

标题层级（Heading 1/2/3 → #/##/###）
通过 run 检测实现粗体/斜体等内联格式
通过 w:numPr XML 元素支持嵌套列表
表格 → Markdown 表格格式
自动跳过 TOC 条目（样式为 toc 1、toc 2 等）

真实场景转换经验总结：

uvx markitdown 在 Windows 上可能因 onnxruntime DLL 加载失败而报错
python-docx 稳定可靠，但不支持图片提取；如需保留图片，请务必使用 pandoc

其他格式转换（markitdown 回退方案）
对于非 .docx 格式，在可用时优先使用 uvx markitdown：
# PDF
uvx markitdown input.pdf -o output.md

# PowerPoint
uvx markitdown input.pptx -o output.md

# Excel
uvx markitdown input.xlsx -o output.md

# HTML、CSV、JSON、XML
uvx markitdown input.html -o output.md
uvx markitdown input.csv -o output.md

# 使用文件类型提示（适用于 stdin 输入）
cat document | uvx markitdown -x .pdf > output.md

# 对复杂 PDF 使用 Azure Document Intelligence
uvx markitdown scan.pdf -d -e "https://your-resource.cognitiveservices.azure.com/"

注意：markitdown 在部分 Windows 系统上可能因 onnxruntime DLL 问题而失败。此时请改用格式专用替代方案（例如：PPTX 使用 python-pptx，XLSX 使用 openpyxl）。
输出结构
project/
├── input.docx          # 源文档
├── output.md           # 转换后的 Markdown 文件
└── img/                # 提取的图片（仅 pandoc 方案生成）
    ├── image1.png
    ├── image2.jpeg
    └── ...

注意事项

强烈推荐使用 pandoc 进行 .docx 转换 —— 它对标题、表格、列表、代码块及各类格式的支持远优于手工解析的 python-docx 方案
.emf 格式（Windows 图元文件）在多数 Markdown 查看器中不受支持；如有需要，建议转换为 PNG 格式
图片文件名沿用 Word 内部命名规则（如 image1.png、image2.png 等）
始终使用 gfm（GitHub Flavored Markdown）作为输出格式，以获得最佳兼容性
在 Windows 上，请通过 py script.py 运行 Python 脚本，而非直接在 PowerShell 中内联执行（避免转义问题）
python-docx 回退方案支持：标题层级、粗体/斜体格式、嵌套列表、表格，并自动跳过 TOC 条目