markdown-tools

Markdown 工具

通过智能多工具编排，将文档转换为高质量 Markdown。

双模式架构

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

快速开始

安装

# Required: PDF/DOCX/PPTX support
uv tool install "markitdown[pdf]"
pip install pymupdf4llm
brew install pandoc

基本转换

# Quick Mode (default) - fast, single best tool
uv run --with pymupdf4llm --with markitdown scripts/convert.py document.pdf -o output.md

# Heavy Mode - multi-tool parallel execution with merge
uv run --with pymupdf4llm --with markitdown scripts/convert.py document.pdf -o output.md --heavy

# Check available tools
uv run scripts/convert.py --list-tools

工具选择矩阵

格式	Quick 模式工具	Heavy 模式工具
PDF	pymupdf4llm	pymupdf4llm + markitdown
DOCX	pandoc	pandoc + markitdown
PPTX	markitdown	markitdown + pandoc
XLSX	markitdown	markitdown

工具特性

• pymupdf4llm：针对大模型优化的 PDF 转换工具，支持原生表格检测和图像提取
• markitdown：Microsoft 的通用转换工具，适用于 Office 格式
• pandoc：出色地保留 DOCX/PPTX 的结构

Heavy 模式工作流

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

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

合并标准

片段类型	选择标准
表格	行列更多，包含正确的表头分隔符
图像	存在替代文本，优先使用本地路径
标题	层级正确，长度合适
列表	项目更多，保留嵌套结构
段落	内容完整性

图像提取

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

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

输出：

• 图像：assets/img_page1_1.png、assets/img_page2_1.jpg
• 元数据：assets/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 → WSL conversion
python scripts/convert_path.py "C:\Users\name\Documents\file.pdf"
# Output: /mnt/c/Users/name/Documents/file.pdf

常见问题

“没有可用的转换工具”

# 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 模式的主编排器
merge_outputs.py	合并多个 Markdown 输出
validate_output.py	使用 HTML 报告进行质量验证
extract_pdf_images.py	提取 PDF 图像并生成元数据
convert_path.py	Windows 到 WSL 的路径转换器

参考资料

• references/heavy-mode-guide.md - Heavy 模式详细文档
• references/tool-comparison.md - 工具功能对比
• references/conversion-examples.md - 批量操作示例