DOCX 转 Markdown
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_84858577/docx2md。
技能介绍
为什么需要它
把 .docx 交给通用转换工具,常见结果是 Markdown 里混着 <table>、<img> 和样式属性,图片落在 media/ 子目录或绝对路径,本地预览直接挂链;Pandoc 能转结构,却常把 Word 里的 1 / 1.1 / 1.1.1 标题编号剥掉。若你既要 GitHub Flavored Markdown 可读性,又要图能跟着走,就需要一条固定流水线,而不是临时拼命令。
技能如何工作
本技能以 Pandoc 为主路径:提取嵌入图片、输出 GFM,再交给 scripts/clean_md.py 做后处理——扁平化 img/media/、修正引用、把 HTML 表格(含 colspan/rowspan)收成 Markdown 表格,并清掉多余 HTML。需要还原编号时,用 scripts/add_heading_numbers.py 读原始 docx 的 OOXML(styles、numbering、document),把编号写回 # 标题行。
Pandoc 装不上时,走 scripts/docx_to_md.py(python-docx):标题、粗斜体、嵌套列表、表格和跳过 TOC 样式仍可用,但 不抽图片。PDF、PPTX、XLSX 等非 docx 格式可在环境允许时用 uvx markitdown 降级;Windows 上 markitdown 偶发 onnxruntime DLL 问题,需换格式专用方案。多文档批量转换时,应为每份文档使用独立图片目录(如 img_v1.0),避免 image1.png 互相覆盖。
边界与注意
.emf 在多数 Markdown 查看器里支持差,必要时先转 PNG。无论主路径还是降级,转换后都应跑一遍 clean_md.py,否则路径错误和 HTML 表格是最常见的两类残留。
使用场景
- 产品或架构同学把带截图的 Word 需求说明转成仓库里的 `.md`,并保留 1.1.1 式标题编号
- Pandoc 转出的 Markdown 里表格仍是 HTML、图片路径指向 `media/`,需要统一清理后再提交 Git
- 多份版本文档(v1.0、v1.1)批量转 Markdown,且每份文档的图片目录互不覆盖
- 内网只有 docx 交付物,需在无法安装 Pandoc 的机器上先得到可读的 md 正文(可暂不要图片)
适合人员
- 维护 GitHub/GitLab 文档、源文件却是 Word 的技术写作者,需要 GFM 且图能本地预览
- 把内部设计/评审 Word 归档进代码库的研发,讨厌 md 里残留 HTML 标签
- 负责知识库迁移的工程师,要把历史 docx 批量转成 md 并还原 Word 多级标题编号
- 在 Windows 环境做文档流水线的人,遇到过 markitdown 或 Pandoc 后处理不一致的问题