GuruDevvv/my-claude-skills / external/doc-to-markdown
doc-to-markdown
VerifiedConverts DOCX/PDF/PPTX to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks. Benchmarked best-in-class (7.6/10) against Docling, MarkItDown, Pandoc raw, and Mammoth. Trigger on "convert document", "docx to markdown", "parse word", "doc to markdown", "解析word", "转换文档".
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.9 KB |
| SKILL.md | skill md | 6.9 KB |
| references/benchmark-2026-03-22.md | markdown | 6.2 KB |
| references/conversion-examples.md | markdown | 6.6 KB |
| references/heavy-mode-guide.md | markdown | 3.8 KB |
| references/tool-comparison.md | markdown | 3.7 KB |
| scripts/convert.py | script | 39.1 KB |
| scripts/convert_path.py | script | 1.4 KB |
| scripts/extract_pdf_images.py | script | 7.6 KB |
| scripts/merge_outputs.py | script | 13.2 KB |
| scripts/test_convert.py | script | 9.4 KB |
| scripts/validate_output.py | script | 16.2 KB |
| КАК_ИСПОЛЬЗОВАТЬ.md | markdown | 491 B |
references/benchmark-2026-03-22.md
View on GitHub# DOCX→Markdown 转换方案基准测试
> **测试日期**:2026-03-22
>
> **测试文件**:`助教-【腾讯云🦞】小白实践 OpenClaw 保姆级教程.docx`(19MB,77 张图片,含 grid table 布局、JSON 代码块、多列图片并排、信息框)
>
> **测试方法**:5 个方案对同一文件转换,按 5 个维度各 10 分制打分
---
## 综合评分
| 维度 | Docling (IBM) | MarkItDown (MS) | Pandoc | Mammoth | **doc-to-markdown(我们)** |
|------|:---:|:---:|:---:|:---:|:---:|
| 表格质量 | 5 | 3 | 5 | 1~3 | **6** |
| 图片提取 | 4 | 2 | **10** | 5 | 7 |
| 文本完整性 | 8 | 7 | **9** | 7 | **9** |
| 格式清洁度 | 5 | 5 | 5 | 3 | **7** |
| 代码块 | 2 | 1 | N/A | 1 | **9** |
| **综合** | **4.8** | **3.6** | **7.3** | **3.4~3.6** | **7.6** |
---
## 各方案详细分析
### 1. IBM Docling(综合 4.8)
- **版本**:docling 2.x + Granite-Docling-258M
- **架构**:AI 驱动(VLM 视觉语言模型),DocTags 中间格式 → Markdown
**致命问题**:
- 图片引用全部是 `<!-- image -->` 占位符(77 张图 0 张可显示),`ImageRefMode` API 对 DOCX 不可用
- 标题层级全部丢失(0 个 `#`),所有标题退化为粗体文本
- 代码块为零,JSON 和命令全部输出为普通段落
- `api_key` 被错误转义为 `api\_key`
**优点**:
- 文本内容完整,中文/emoji/链接保留良好
- 无 grid table 或 HTML 残留
- 表格语法正确(pipe table),但内容是占位符
**结论**:Docling 的优势在 PDF(AAAI 2025 论文场景),DOCX 支持远未达到生产级别。
### 2. Microsoft MarkItDown(综合 3.6)
- **版本**:markitdown 0.1.5
- **架构**:底层调用 mammoth → HTML → markdownify → Markdown
**致命问题**:
- 77 张图片全部是截断的 base64 占位符(`data:image/png;base64,...`),默认 `keep_data_uris=False` 主动丢弃图片数据
- 标题全部变为粗体文本(mammoth 无法识别 WPS 自定义样式)
- 代码块为零,JSON 被塞入表格单元格
- 有序列表编号全部错误(输出为 `1. 1. 1.`)
**优点**:
- 无 HTML 标签残留
- 文本内容基本完整
**结论**:MarkItDown 的 markdownify 后处理反而引入破坏性截断。轻量场景可用,复杂 DOCX 不可靠。
### 3. Pandoc(综合 7.3)
- **版本**:pandoc 3.9
- **架构**:Haskell 原生 AST 解析,支持 60+ 格式
**测试了 3 种参数**:
| 参数 | 结果 |
|------|------|
| `-t gfm` | 最差:24 个 HTML `<table>` 嵌套,74 个 HTML `<img>` |
| `-t markdown` | 最佳:grid table(可后处理),无 HTML |
| `-t markdown-raw_html-...` | 与 markdown 完全相同,参数无效果 |
**问题**:
- Grid table 不可避免(原 docx 有多行单元格和嵌套表格,pipe table 无法表达)
- `{width="..." height="..."}` 68 处
- `{.underline}` 6 处
- 反斜杠过度转义 37 处
**优点**:
- 图片提取 10/10(77 张全部正确,路径结构一致)
- 文本完整性 9/10(内容、链接、emoji 全部保留)
- 最成熟稳定的底层引擎
**结论**:Pandoc 是最可靠的底层引擎,输出质量最高但需要后处理清洗 pandoc 私有语法。
### 4. Mammoth(综合 3.4~3.6)
- **版本**:mammoth 1.11.0
- **架构**:python-docx 解析 → HTML/Markdown(Markdown 支持已废弃)
**测试了 2 种方式**:
| 方式 | 综合 |
|------|------|
| 方式A:直接转 Markdown | 3.4(表格完全丢失) |
| 方式B:转 HTML → markdownify | 3.6(有表格但嵌套被压扁) |
**致命问题**:
- 标题全部丢失(WPS `styles.xml` 中样式定义为空,mammoth 无法映射 Heading)
- 代码块为零
- 图片全部 base64 内嵌,单文件 28MB
- 方式B 中 markdownify 丢失 14 张图片(63/77)
**结论**:Mammoth 的 Markdown 支持已废弃,对 WPS 导出的 docx 兼容性差。不推荐。
### 5. doc-to-markdown / 我们的方案(综合 7.6)
- **版本**:doc-to-markdown 1.0(基于 pandoc + 6 个后处理函数)
- **架构**:Pandoc 转换 → 自动后处理(grid table 清理、图片路径修复、属性清理、代码块修复、转义修复)
**后处理实际效果**:
| 后处理函数 | 修复数量 |
|-----------|---------|
| `_convert_grid_tables` | 11 处 grid table → pipe table / blockquote |
| `_clean_pandoc_attributes` | 3437 字符属性清理 |
| `_fix_code_blocks` | 22 处缩进虚线 → ``` 代码块 |
| `_fix_escaped_brackets` | 10 处 |
| `_fix_double_bracket_links` | 1 处 |
| `_fix_image_paths` | 77 张图片路径修复 |
**已知问题(待修复)**:
- 图片路径双层嵌套 bug:`--assets-dir` 指定目录内被 pandoc 再建一层 `media/`
- 2 处 grid table 残留(文末并排图片组未完全转换)
**优点**:
- 代码块识别 9/10(JSON 带语言标签,命令行正确包裹)
- 格式清洁度 7/10(attributes、转义、grid table 大部分清理干净)
- 文本完整性 9/10(关键内容全部保留)
**结论**:综合最优,核心价值在 pandoc 后处理层。剩余 2 个 bug 可修。
---
## 架构决策
```
最终方案:Pandoc(底层引擎)+ doc-to-markdown 后处理(增值层)
理由:
1. Pandoc 图片提取最可靠(10/10),文本最完整(9/10)
2. Pandoc 的问题(grid table、属性、转义)全部可后处理解决
3. Docling/MarkItDown/Mammoth 的致命问题(图片丢失、标题丢失)无法后处理修复
4. 后处理层是我们的核心竞争力,成本低、可迭代
```
---
## 测试文件特征
本次测试文件的难点在于:
| 特征 | 说明 | 影响 |
|------|------|------|
| WPS 导出 | 非标准 Word 样式(Style ID 2/3 而非 Heading 1/2) | mammoth/markitdown/docling 标题全丢 |
| 多列图片布局 | 2x2、1x4 图片网格用表格排版 | pandoc 输出 grid table |
| 信息框/提示框 | 单列表格包裹文字 | pandoc 输出 grid table |
| 嵌套表格 | 表格内套表格 | pipe table 无法表达 |
| JSON 代码块 | 非代码块样式,用文本框/缩进表示 | 多数工具无法识别为代码 |
| 19MB 文件 | 77 张截图嵌入 | base64 方案导致 28MB 输出 |
这些特征代表了真实世界中 WPS/飞书文档导出 docx 的典型困难,是有效的基准测试场景。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |