doc-to-markdown

将文档转换为 Markdown

借助智能多工具编排和自动 DOCX 后处理，将文档转换为高质量 Markdown。

架构：Pandoc（业界领先的提取工具）+ 8 项后处理修复（我们的增值功能）。

快速开始

# DOCX → Markdown (one command, zero manual fixes)
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

# Saved HTML → Markdown (Pandoc required; no remote fetching)
uv run scripts/convert.py page.html -o page.md

# Run tests
uv run --with pytest pytest scripts/test_convert.py -v

双模式

模式	速度	质量	使用场景
快速（默认）	快	良好	草稿、简单文档
重型	较慢	最佳	最终文档、复杂版式

工具选择

格式	快速模式	重型模式
PDF	pymupdf4llm	pymupdf4llm + markitdown
DOCX	pandoc + 后处理	pandoc + markitdown
PPTX	markitdown	markitdown + pandoc
XLSX	markitdown	markitdown
HTML/HTM	pandoc + 源 href 保留检查	不支持；请使用 HTML 快速路径

已保存的 HTML 和网站手册

转换 HTML/HTM 前，请阅读 references/html-conversion.md。 使用 scripts/convert.py；默认会转换整个正文，不会裁剪导航内容。显式指定 --html-selector 可选择且仅选择一个标签、#id 或 .class。--html-heading-offset 会在组装时调整解析出的标题级别，超出 H6 时将报错。不会下载或复制相对资源。

检查源文件中的 href 是否都出现在输出的 Markdown AST 中，然后在清理或合并后重新运行 scripts/html_to_markdown.py。对于手册，请在组装前梳理书籍、章节、课时和内部标题； 保留代码围栏并核对重写后的锚点。转换成功并不意味着图表在接收方实际使用的 Markdown 阅读器中清晰可读。

DOCX 后处理（自动）

通过 pandoc 转换 DOCX 时，会自动应用 8 项清理：

问题	修复	测试覆盖
网格表（+:---+）	单列 → 引用块，多列 → 管道表	TestPostprocessPipeline
简单表（ ---- ----）	多列图片 → 带标题的管道表	TestSimpleTable
图片路径嵌套（media/media/）	扁平化为 media/，绝对路径 → 相对路径	test_stats_tracking
Pandoc 属性（{width="..."}）	移除	test_pandoc_attributes_removed
CJK 粗体间距（**粗体**中文）	在 CJK 粗体片段的 ** 周围添加空格	TestCjkBoldSpacing（15 个用例）
缩进的虚线代码块	→ 带语言检测的围栏代码块	test_code_block_with_language
转义方括号（\[...\]）	→ [...]	test_escaped_brackets_fixed
双方括号链接（[[text]](url)）	→ [text](url)	test_double_bracket_links_fixed

PDF 后处理（自动，始于 2026-08-30）

通过 pymupdf4llm 转换 PDF 时，会自动应用 3 项清理（使用 --no-postprocess 跳过）：

问题	修复	测试覆盖
图像区域中的 Tesseract OCR 垃圾文本（...）	移除文本块；保留图像本身	TestStripOcrPictureText
重复的页眉、页脚或水印行（相同的规范化行出现在 ≥60% 的页面上，包括对角水印）	通过 pymupdf 跨页扫描检测，并从 Markdown 中移除；也能识别加粗包裹及与页码合并的变体	TestRepeatingLines
绝对图像路径（）	改写为相对于输出 Markdown 文件的路径（便于移植的输出）	TestImagePathsRelative

当某个引擎失败，且合并原本会悄然退化为单引擎输出时，Heavy 模式还会在 stderr 上打印醒目的 ⚠️ HEAVY MODE DEGRADED 警告。

已知限制（根据 2026-08-30 对一份 62 页中文研究报告的转换结果总结）：

• pymupdf4llm 可能会生成重复段落（源文本层中只有一份）——不会自动修复；请抽查。
• 带点线的目录页会被识别为表格——如果有影响，请手动重写目录。
• 不会合并跨页表格（每页的片段都保留各自的标题行）——请手动合并。
• 被对角水印覆盖的表格单元格可能包含水印字符碎片（dn、uFE 等）；重复行剥离器只会移除整行，不会处理单元格内的碎片。水印较多的 PDF 需要在单元格级别重建（收集每个单元格边界框中非水印的文本范围）。
• 复杂的信息图（图像内文字密集）只会输出为图像；要转录图像内文字，需要经过 VLM 处理，而不是使用此工具。

CJK 粗体间距——原因与方法

DOCX 使用运行级样式（CJK 文本中的粗体与常规文本运行之间没有空格）。Markdown 渲染器需要在 ** 两侧留出空白，才能识别粗体边界。

规则：如果 **content** 片段中包含任何 CJK 字符，则确保两侧各有一个空格——除非已有空格或位于行边界处。这样可以处理 CJK 标点、相邻 emoji 以及混合内容。

Before: 打开**飞书**，就可以    → some renderers fail to bold
After:  打开 **飞书** ，就可以  → universally renders correctly

Heavy 模式工作流

Heavy 模式会并行运行多个工具，并选择最佳片段：

1. 并行执行：同时运行所有适用的工具
2. 片段分析：将每个输出解析为片段（表格、标题、图像、段落）
3. 质量评分：根据完整性和结构为每个片段评分
4. 智能合并：从各工具的输出中为每个片段选择最佳版本

合并标准

片段类型	选择标准
表格	行数/列数更多，标题分隔行格式正确
图像	包含替代文本，优先选择本地路径
标题	层级正确，长度适当
列表	条目更多，保留嵌套结构
段落	内容完整性

图像提取

# Extract images with metadata
uv run --with pymupdf scripts/extract_pdf_images.py document.pdf -o ./extracted-images

# Generate markdown references file
uv run --with pymupdf scripts/extract_pdf_images.py document.pdf --markdown refs.md

输出：

• 图像：extracted-images/img_page1_1.png、extracted-images/img_page2_1.jpg
• 元数据：extracted-images/images_metadata.json（页面、位置、尺寸）

质量验证

# Validate conversion quality
uv run --with pymupdf scripts/validate_output.py document.pdf output.md

# Generate HTML report
uv run --with pymupdf scripts/validate_output.py document.pdf output.md --report report.html

质量指标

指标	通过	警告	失败
文本保留率	>95%	85-95%	<85%
表格保留率	100%	90-99%	<90%
图像保留率	100%	80-99%	<80%

手动合并输出

# Merge multiple markdown files
python scripts/merge_outputs.py output1.md output2.md -o merged.md

# Show segment attribution
python scripts/merge_outputs.py output1.md output2.md -o merged.md --verbose

路径转换（Windows/WSL）

# Windows to WSL conversion
python scripts/convert_path.py "C:\Users\<windows-user>\Documents\file.pdf"
# Output: /mnt/c/Users/<windows-user>/Documents/file.pdf

常见问题

“No conversion tools available”

# Install all tools
pip install pymupdf4llm
uv tool install "markitdown[pdf]"
brew install pandoc

PDF 转换期间出现 FontBBox 警告

• 无害的字体解析警告，输出仍然正确

输出中缺少图像

• 使用 Heavy 模式以更好地保留图像
• 或使用 scripts/extract_pdf_images.py 单独提取

输出中的表格损坏

• 使用 Heavy 模式——它会选择最完整的表格版本
• 或使用 scripts/validate_output.py 进行验证

随附脚本

脚本	用途
convert.py	主协调器，包含 Quick/Heavy 模式和 DOCX 后处理
html_to_markdown.py	Pandoc HTML 适配器和已保存输出的源 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 - Heavy Mode 详细文档
• references/tool-comparison.md - 工具能力比较
• references/conversion-examples.md - 批量操作示例
• references/html-conversion.md - 已保存 HTML 的范围、链接保留、资源和手动标题组装

下一步：清理转换后的内容

将文档转换为 Markdown 后，建议进行清理：

Conversion complete: [N] files converted to markdown.

Options:
A) Clean up docs — run /daymade-docs:docs-cleaner to consolidate redundant content (Recommended if multiple files)
B) Check facts — run /fact-checker to verify claims in the converted content
C) No thanks — the markdown conversion is sufficient