SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场doc-to-markdown

doc-to-markdown

办公与效率

查看项目

更新于 10-15 15:00

技能介绍

用途

doc-to-markdown 用于把常见文档格式转换为高质量 Markdown。支持 DOCX、PDF、PPTX、XLSX，以及已保存的 HTML/HTM 文件。其定位是“智能多工具编排 + 自动后处理”：以 Pandoc 等工具做提取，再叠加自有的后处理修复，减少手工整理。

主要能力

  • 多格式转换：DOCX、PDF、PPTX、XLSX、HTML/HTM。
  • 双模式：Quick（默认，速度快、质量良好，适合草稿与简单文档）与 Heavy（较慢、质量最佳，适合最终文档与复杂版式）。
  • 工具选择：PDF 在 Quick 模式用 pymupdf4llm，Heavy 模式用 pymupdf4llm + markitdown；DOCX 在 Quick 模式用 pandoc + 后处理，Heavy 模式用 pandoc + markitdown；PPTX 在 Quick 模式用 markitdown，Heavy 模式用 markitdown + pandoc；XLSX 两种模式均用 markitdown；HTML/HTM 在 Quick 模式用 pandoc 并做 source-href 保留检查，Heavy 模式不支持，需走 HTML quick 路径。
  • DOCX 自动后处理（8 项）：网格表（单列转引用块、多列转管道表）、简单表（多列图片转带标题的管道表）、图片路径嵌套（media/media/ 扁平化为 media/，绝对路径转相对）、移除 Pandoc 属性（如 {width="..."}）、CJK 粗体间距、缩进短横线代码块转带语言检测的围栏代码块、转义方括号还原、双方括号链接还原。
  • PDF 自动后处理（3 项，可用 --no-postprocess 跳过）：移除图片区域上的 Tesseract OCR 垃圾块（保留图片本身）、检测并移除重复页眉/页脚/水印行（同一规范化行出现在 ≥60% 页面，含对角水印；加粗包裹与合并页码的变体也能捕获）、绝对图片路径改写为相对输出 Markdown 文件的路径。
  • Heavy 模式工作流：并行执行所有适用工具，将各输出解析为段落（表格、标题、图片、段落），按完整性与结构评分，再跨工具为每类段落选择最佳版本合并。合并标准：表格看行列数与表头分隔符，图片看 alt 文本与本地路径，标题看层级与长度，列表看条目数与嵌套结构，段落看内容完整性。
  • 质量校验：validate_output.py 可对比源文档与输出，给出文本保留率、表格保留率、图片保留率指标（通过/警告/失败阈值），并可生成 HTML 报告。
  • 图片提取：extract_pdf_images.py 可提取 PDF 图片并输出元数据（页码、位置、尺寸），也可生成 Markdown 引用文件。
  • 其他脚本：merge_outputs.py 合并多个 Markdown 输出（可显示段落归属），convert_path.py 做 Windows 到 WSL 路径转换。

使用方式

DOCX 转 Markdown（一条命令，零手工修复）： uv run --with pymupdf4llm --with markitdown scripts/convert.py document.docx -o output.md --assets-dir ./media

PDF 转 Markdown： uv run --with pymupdf4llm --with markitdown scripts/convert.py document.pdf -o output.md

已保存 HTML 转 Markdown（需要 Pandoc；不远程抓取）： uv run scripts/convert.py page.html -o page.md

运行测试： uv run --with pytest pytest scripts/test_convert.py -v

提取 PDF 图片： uv run --with pymupdf scripts/extract_pdf_images.py document.pdf -o ./extracted-images uv run --with pymupdf scripts/extract_pdf_images.py document.pdf --markdown refs.md

质量校验： uv run --with pymupdf scripts/validate_output.py document.pdf output.md uv run --with pymupdf scripts/validate_output.py document.pdf output.md --report report.html

合并输出： python scripts/merge_outputs.py output1.md output2.md -o merged.md python scripts/merge_outputs.py output1.md output2.md -o merged.md --verbose

路径转换： python scripts/convert_path.py "C:\Users<windows-user>\Documents\file.pdf"

HTML/HTM 转换前需阅读 references/html-conversion.md。默认转换整个 body 且不裁剪导航；显式 --html-selector 可精确选择一个标签、#id 或 .class；--html-heading-offset 可平移解析出的标题用于组装，超出 H6 会被拒绝。相对资源不会被下载或复制。需将源 href 出现次数与生成的 Markdown AST 核对，清理或合并后重跑 scripts/html_to_markdown.py。手册类文档需先梳理书、章、课与内部标题再组装，保留代码围栏并核对重写后的锚点。转换成功并不代表图片在接收方实际 Markdown 阅读器中可读。

适用场景

  • 将 DOCX/PDF/PPTX/XLSX 文档批量转为 Markdown，用于知识库、文档站或版本管理。
  • 处理含中文内容的文档（CJK 粗体间距修复）。
  • 需要保留表格、图片与标题层级的复杂版式文档（建议 Heavy 模式）。
  • 将已保存的网页/网站手册转为 Markdown 并核对链接保留。
  • 对转换结果做质量校验与多输出合并。

限制

  • HTML/HTM 的 Heavy 模式不支持，需使用 HTML quick 路径；相对资源不下载、不复制。
  • PDF 已知限制（来自一次 62 页中文研究报告转换）：pymupdf4llm 可能输出重复段落，不会自动修复，需抽查；点线目录页会被识别为表格，必要时手工重写；跨页表格不会合并，每页片段保留各自表头，需手工合并；被对角水印覆盖的表格单元格可能残留水印字符碎片（如 dn、uFE），重复行清理只移除整行、不移除单元格内碎片，水印密集的 PDF 需按单元格 bbox 重建；复杂信息图（图内文字密集）只会以图片形式输出，转录图内文字需要 VLM 处理，本工具不提供。
  • Heavy 模式在某引擎失败、合并会静默退化为单引擎输出时，会在 stderr 打印 ⚠️ HEAVY MODE DEGRADED 警告。
  • 常见问题：提示“No conversion tools available”时需安装工具（pip install pymupdf4llm；uv tool install "markitdown[pdf]"；brew install pandoc）；PDF 转换中的 FontBBox 警告无害；图片缺失可用 Heavy 模式或单独提取；表格损坏可用 Heavy 模式或质量校验。
  • 转换完成后可选的后续清理（如 /daymade-docs:docs-cleaner 合并冗余内容、/fact-checker 核查事实）属于建议步骤，非本工具内置功能。

附带脚本

convert.py（主编排，含 Quick/Heavy 模式与 DOCX 后处理）、html_to_markdown.py（Pandoc HTML 适配器与已保存输出的 source-href 保留校验）、test_convert.py（31 项测试覆盖全部后处理函数）、merge_outputs.py（合并多个 Markdown 输出）、validate_output.py（质量校验并生成 HTML 报告）、extract_pdf_images.py（PDF 图片提取与元数据）、convert_path.py（Windows 到 WSL 路径转换）。

参考资料：references/benchmark-2026-03-22.md（5 工具基准：Docling/MarkItDown/Pandoc/Mammoth/本工具）、references/heavy-mode-guide.md、references/tool-comparison.md、references/conversion-examples.md、references/html-conversion.md。