Hubbestaiskill.com

Home / All Skills / Docs & Knowledge / doc-to-markdown

Docs & Knowledge · 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 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandData ExfiltrationNetwork AccessWrite FileDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Implemented via a two-layer architecture: 'Pandoc extraction + value-add post-processing'. SKILL.md explicitly fixes this architecture, asserting that core value lies in the 8 DOCX post-processing steps rather than the raw conversion itself.

daymade-docs/doc-to-markdown/SKILL.md

**Architecture**: Pandoc (best-in-class extraction) + 8 post-processing fixes (our value-add).

convert.py first selects the tool by file extension (DOCX→pandoc, PDF→pymupdf4llm, PPTX/XLSX→markitdown), then applies regex-level cleanup on pandoc/pymupdf4llm output to normalize engine-specific syntax (grid tables, {width=...} attributes, nested media/media/ paths, etc.) into standard markdown.

Tool selection routes via Quick/Heavy dual modes: Quick mode runs a single tool rapidly, while Heavy mode executes multiple tools in parallel and merges segments (tables/images/headings/lists/paragraphs) by picking the best candidate according to quality scoring.

daymade-docs/doc-to-markdown/SKILL.md

| PDF | pymupdf4llm | pymupdf4llm + markitdown |

For DOCX under the same table, the row transitions from pandoc → pandoc+markitdown; the parallel execution and merge criteria for Heavy mode are detailed in the 'Heavy Mode Workflow' section ('Parallel Execution: Run all applicable tools simultaneously') of the same document.

DOCX post-processing is backed category-by-category by tests: all 8 cleanup tasks (grid/simple tables, image paths, pandoc attributes, CJK bold spacing, indented code blocks, escaped brackets, double-bracket links) map directly to tests in SKILL.md such as TestPostprocessPipeline and TestCjkBoldSpacing (15 cases).

daymade-docs/doc-to-markdown/SKILL.md

| Grid tables (`+:---+`) | Single-column → blockquote, multi-column → pipe table | `TestPostprocessPipeline` |

CJK bold spacing is a known friction point between DOCX run-level styles and markdown renderers; it is resolved using a heuristic rule where 'spans containing CJK characters are padded with spaces on both sides'—a classic case of codifying Chinese typography knowledge.

PDF post-processing (since 2026-08-30) performs three tasks: stripping Tesseract OCR garbage blocks, removing cross-page repeated headers/footers/watermark lines (identified when a normalized line appears on ≥60% of pages), and converting absolute image paths to relative ones.

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`

Watermark/header removal relies on pymupdf cross-page statistics (_detect_repeating_lines) rather than purely text-based processing; SKILL.md also candidly lists known limitations (repeated paragraphs, dot-leader TOC parsed as tables, cross-page tables not merged, etc.).

The quality loop is supported by validate_output.py: it provides Pass/Warn/Fail thresholds based on retention rates of text, tables, and images, and can generate HTML reports.

daymade-docs/doc-to-markdown/SKILL.md

| Text Retention | >95% | 85-95% | <85% |

This script uses pdftotext to extract PDF text and compares it against the output markdown (scripts/validate_output.py calls subprocess.run(['pdftotext', '-layout', ...])), quantifying whether anything was lost during conversion.

The best-in-class (7.6/10) claim is backed by in-repo benchmark documents: scoring Docling/MarkItDown/Pandoc/Mammoth dimension-by-dimension, concluding in favor of a pandoc foundation combined with a post-processing layer.

daymade-docs/doc-to-markdown/references/benchmark-2026-03-22.md

| 维度 | Docling (IBM) | MarkItDown (MS) | Pandoc | Mammoth | **doc-to-markdown（我们）** |

The SKILL.md description and the benchmark files corroborate each other; the README characterizes the development culture behind this document family as 'benchmark-first'.

2Core Capabilities

01Single-command conversion from DOCX/PDF/PPTX/XLSX to high-quality Markdown (Quick mode by default)

028-step automatic cleanup for pandoc output (grid/simple tables, attribute noise, image paths, CJK bold spacing, code blocks, escaped characters, double-bracket links)

03Automatic removal of PDF watermarks, headers, footers, and OCR garbage, plus portable image path rewriting

04Heavy mode multi-tool parallel execution with segment-level quality merging (criteria: table row counts, image alt text, heading hierarchy, etc.)

05PDF image extraction (with page number, coordinates, dimension metadata, and markdown reference files)

06Conversion quality validation and HTML reporting (three-tier Pass/Warn/Fail thresholds for text/table/image retention rates)

07Windows/WSL path conversion helper

3External Dependencies

Kind	Dependency / Endpoint
cli	pandoc
cli	markitdown CLI（markitdown[pdf]）
package	pymupdf4llm / pymupdf（uv --with 拉取）
cli	pdftotext / pdftoppm（poppler，校验脚本用）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: python scripts/convert.py (local parsing + post-processing)
外部端点: Exfiltrates local content or conversation data to third-party cloud storage
本地工作目录: File I/O and artifact output: -o writes markdown output; --assets-dir saves images to disk (flattening media/); extract_pdf_images/validate_out

Audit Notes: Pure local conversion pipeline: only invokes local CLI and Python libraries, with no runtime network transmission and no credential access; reading and writing user documents is core to its functionality. Initial environment bootstrapping requires PyPI access (via uv --with), where outbound traffic targets official package registries and is entirely expected.

5Second-Pass Verification

[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。

6Verdict & Scenarios

Engine choices are backed by empirical benchmarks, post-processing steps are individually covered by tests, and all claimed 8+3 cleanup operations are traceable in code.

Codifies Chinese typography rules (CJK bold spacing, CJK in code blocks), delivering localized enhancements rarely found in similar conversion tools.

Heavy mode turns 'multi-tool competitive selection' into a practical feature, compensating for single-engine weaknesses (table and image retention).

Honest disclosure of known limitations (e.g., 5 categories of unhandled issues across 62-page research reports), establishing well-managed delivery expectations.

Best for: Ideal for scenarios requiring 'document to editable markdown' with high demands on Chinese typography, table preservation, and image extraction (batch conversion of research reports, contracts, book manuscripts, and technical docs); actively maintained by authors with thorough testing, making it production-pipeline ready. Heavy mode is reserved for final drafts with complex layouts.

Not for: Not suitable for PDF layout requirements that demand pixel-perfect visual fidelity (which belongs to pdf-to-html/pdf-creator tools); not suitable for environments without uv or internet access (high dependency bootstrap cost); heavily watermarked PDFs and pure scanned documents (without text layers) exceed its capabilities and require prior 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

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.