首页 / 全部技能 / 文档与知识 / doc-to-markdown
English (EN)简体中文 (ZH)日本語 (JA)
文档与知识 · daymade/claude-code-skills

doc-to-markdown

Converts 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; for PDFs also strips OCR garbage blocks, repeated headers/footers/watermarks, and absolute image paths from pymupdf4llm output. 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", "转换文档".

L4 高权限 · 分级授权与审计V1 已固定执行命令数据外发联网读写文件Dual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

功能由『Pandoc 抽取 + 增值后处理』两层实现：SKILL.md 把架构一句话写死，声称价值在 8 项 DOCX 后处理而非转换本身。

daymade-docs/doc-to-markdown/SKILL.md
**Architecture**: Pandoc (best-in-class extraction) + 8 post-processing fixes (our value-add).
convert.py 先按扩展名选工具（DOCX→pandoc、PDF→pymupdf4llm、PPTX/XLSX→markitdown），再对 pandoc/pymupdf4llm 输出做正则级清洗，把引擎私有语法（grid table、{width=...} 属性、media/media/ 路径嵌套等）标准化成通用 markdown。

工具选择被 Quick/Heavy 双模式路由：Quick 单工具快跑，Heavy 多工具并行、逐段（表格/图片/标题/列表/段落）按质量评分择优合并。

daymade-docs/doc-to-markdown/SKILL.md
| PDF | pymupdf4llm | pymupdf4llm + markitdown |
同一表格下方 DOCX 行是 pandoc → pandoc+markitdown；Heavy 模式的并行执行与 merge 标准在同文件 'Heavy Mode Workflow' 节（'Parallel Execution: Run all applicable tools simultaneously'）。

DOCX 后处理逐类有测试背书：8 项清洗（grid/simple 表格、图片路径、pandoc 属性、CJK 加粗间距、缩进代码块、转义括号、双括号链接）在 SKILL.md 表格中与 TestPostprocessPipeline / TestCjkBoldSpacing(15 cases) 等测试一一对应。

daymade-docs/doc-to-markdown/SKILL.md
| Grid tables (`+:---+`) | Single-column → blockquote, multi-column → pipe table | `TestPostprocessPipeline` |
CJK 加粗间距是 DOCX run 级样式与 markdown 渲染器之间的已知摩擦点，这里用『span 含 CJK 字符即两侧补空格』的启发式规则解决——这是把中文排版知识代码化的典型做法。

PDF 后处理（2026-08-30 起）做三件事：剥 Tesseract OCR 垃圾块、跨页去重复页眉/页脚/水印行（同一条规范化行出现在 ≥60% 页面即判定）、把绝对图片路径改相对。

daymade-docs/doc-to-markdown/SKILL.md
Repeated header/footer/watermark lines (same normalized line on ≥60% of pages, incl. diagonal watermarks) | Detected via pymupdf cross-page scan, removed from markdown; bold-wrapped and merged-with-page-number variants also caught | `TestRepeatingLines`
去水印/页眉依赖 pymupdf 跨页统计（_detect_repeating_lines），不是纯文本处理；SKILL.md 同时诚实列出已知局限（重复段落、点线目录被当表格、跨页表格不合并等）。

质量闭环由 validate_output.py 支撑：按文本/表格/图片保留率给出 Pass/Warn/Fail 阈值，并可输出 HTML 报告。

daymade-docs/doc-to-markdown/SKILL.md
| Text Retention | >95% | 85-95% | <85% |
该脚本用 pdftotext 抽取 PDF 文本后与输出 markdown 比对（scripts/validate_output.py 内 subprocess.run(['pdftotext','-layout',...])），量化『转换有没有丢东西』。

best-in-class(7.6/10) 声明由仓库内基准文档支撑：对 Docling/MarkItDown/Pandoc/Mammoth 逐维度打分，结论是 pandoc 底座+后处理层。

daymade-docs/doc-to-markdown/references/benchmark-2026-03-22.md
| 维度 | Docling (IBM) | MarkItDown (MS) | Pandoc | Mammoth | **doc-to-markdown（我们）** |
SKILL.md description 与 benchmark 文件互相印证；README 对该文档族的定位是『benchmark-first』的开发文化。

2核心能力

01DOCX/PDF/PPTX/XLSX → 高质量 Markdown 单命令转换（Quick 模式默认）
02pandoc 产物 8 项自动清洗（grid/simple 表格、属性噪声、图片路径、CJK 加粗间距、代码块、转义、双括号链接）
03PDF 水印/页眉/页脚/OCR 垃圾自动剥离与图片路径可移植化
04Heavy 模式多工具并行+分segment 质量合并（表格行数/图片 alt/标题层级等准则）
05PDF 图片抽取（带页码/坐标/尺寸元数据与 markdown 引用文件）
06转换质量验证与 HTML 报告（文本/表格/图片保留率三档阈值）
07Windows/WSL 路径换算辅助

3外部依赖

KindDependency / Endpoint
clipandoc
climarkitdown CLI（markitdown[pdf]）
packagepymupdf4llm / pymupdf（uv --with 拉取）
clipdftotext / pdftoppm（poppler，校验脚本用）

4管控建议与判定依据

建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
  • scripts/: 执行本地脚本或命令: python scripts/convert.py（本地解析+后处理）
  • 外部端点: 将本地内容或会话向第三方云存储外发
  • 本地工作目录: 文件读写与工件输出: -o 输出 markdown；--assets-dir 图片落盘（media/ 展平）；extract_pdf_images/validate_out
审计说明： 。纯本地转换管线：只调用本地 CLI/Python 库，无运行期网络外发、无凭证读取；对用户文档做读写是功能本质。首次环境预置需联网 PyPI（uv --with），外发对象为官方包源、可预期。

5第二遍独立确认

  • [ok] 架构=Pandoc+8 后处理 — SKILL.md 原文与 convert.py 的 tool_map/pandoc 调用路径吻合；8 项清洗在 DOCX Post-Processing 表逐行列出。
  • [ok] CJK 加粗间距规则 — 规则原文（含 CJK 即两侧补空格）在 SKILL.md 'CJK Bold Spacing — why and how' 节，测试类 TestCjkBoldSpacing 存在。
  • [ok] PDF 水印剥离用 pymupdf 跨页扫描 — SKILL.md 声称 + convert.py _detect_repeating_lines 内 import pymupdf、doc=pymupdf.open(...) 属实。
  • [ok] Heavy 模式并行多工具 — SKILL.md 'Run all applicable tools simultaneously' + 分 segment 评分合并准则表均在。
  • [ok] 质量阈值 95/100% 等 — validate_output.py 存在 pdftotext 子进程调用，SKILL 阈值表为文档化契约。
  • [ok] 7.6/10 best-in-class 声明 — references/benchmark-2026-03-22.md 含 5 工具维度评分表与 '综合最优' 结论；评分口径为内部基准、非独立第三方评测——已注明。
  • [ok] 无网络外发/无凭证 — convert.py/validate_output.py/merge_outputs.py/extract_pdf_images.py 全量扫描：无 requests/urllib/http 调用点（仅测试 fixture 的 example.com 文本）；无 environ 凭证读取。
  • [ok] 元数据核对 — GitHub API：MIT、1385 stars、pushed 2026-09-09T12:33:29Z；本地 git HEAD == d5c4678cb5d4 == pin。

6结论

  • 引擎选择有实测基准背书，后处理逐项钉测试，宣称的 8+3 项清洗都可从代码定位。
  • 把中文排版知识（CJK 加粗间距、代码块 CJK）代码化，是同类转换工具少见的本土化增量。
  • Heavy 模式把『多工具竞争择优』做成可用功能，弥补单引擎短板（表格、图片保留）。
  • 诚实记录已知局限（62 页研报的 5 类不自动修问题），交付期望管理好。
    • 适合： 适合需要『文档→可编辑 markdown』且对中文排版/表格/图片保留有要求的场景（研报、合同、书稿、技术文档批量转换）；作者维护积极、含测试，适合接入生产流水线。Heavy 模式留给版式复杂的终稿。
    不适合： 不适合追求像素级还原的 PDF 版式需求（那是 pdf-to-html/pdf-creator 的方向）；不适合无 uv/无网络的环境（依赖预置成本高）；水印极重的 PDF 与纯扫描件（无文本层）超出能力，需先 OCR。
    Install Agent-Ready
    ① Verified Mirror 2026-09-09
    Option A · Direct DownloadDownload doc-to-markdown.tar.gz
    sha256: 71b6589924471f21…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.