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：ネイティブな表検出と画像抽出に対応した、LLM 向け 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 - バッチ操作の例