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

2 つのモード

モード	速度	品質	用途
クイック（デフォルト）	高速	良好	下書き、シンプルなドキュメント
ヘビー	低速	最高	最終版のドキュメント、複雑なレイアウト

ツールの選択

形式	クイックモード	ヘビーモード
PDF	pymupdf4llm	pymupdf4llm + markitdown
DOCX	pandoc + 後処理	pandoc + markitdown
PPTX	markitdown	markitdown + pandoc
XLSX	markitdown	markitdown
HTML/HTM	pandoc + source-href の保持確認	非対応。HTML のクイックパスを使用してください

保存済みの HTML とウェブサイトのマニュアル

HTML/HTM の場合は、変換前に references/html-conversion.md を読んでください。scripts/convert.py を使用します。デフォルトでは本文全体を変換し、 ナビゲーション部分は切り取りません。明示的に指定した --html-selector は、タグ、 #id、または .class を 1 つだけ選択します。--html-heading-offset は組み立て時に 解析済みの見出しのレベルをずらし、H6 を超える場合はエラーになります。相対パスの アセットはダウンロードもコピーもされません。

ソース内の href の出現箇所を、出力された Markdown AST と照合して確認し、クリーンアップや マージの後に scripts/html_to_markdown.py を再実行してください。マニュアルの場合は、 組み立てる前に書籍、章、レッスン、内部見出しの対応関係を整理し、コードフェンスを維持して、 書き換えられたアンカーを調整してください。変換が成功しても、受け取り側が実際に使用する Markdown リーダーで図表を読み取れることが保証されるわけではありません。

DOCX の後処理（自動）

Pandoc 経由で DOCX を変換すると、8 件のクリーンアップが自動的に適用されます。

問題	修正	テストカバレッジ
グリッドテーブル（+:---+）	1 列 → 引用ブロック、複数列 → パイプテーブル	TestPostprocessPipeline
シンプルなテーブル（ ---- ----）	画像を含む複数列テーブル → キャプション付きパイプテーブル	TestSimpleTable
画像パスのネスト（media/media/）	media/ にフラット化し、絶対パス → 相対パス	test_stats_tracking
Pandoc 属性（{width="..."}）	削除	test_pandoc_attributes_removed
CJK 太字のスペース（**粗体**中文）	CJK 太字の範囲を囲む ** の前後にスペースを追加	15 ケースの TestCjkBoldSpacing
インデントされた破線のコードブロック	→ 言語検出付きのフェンス付き ```	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 モードではさらに、1 つのエンジンが失敗し、マージ結果が単一エンジンの出力にひそかに劣化する場合、stderr に目立つ ⚠️ HEAVY MODE DEGRADED 警告を出力します。

既知の制限（2026-08-30 に 62 ページの中国語研究レポートを変換して判明）：

• pymupdf4llm は段落を重複して出力する場合があります（元のテキストレイヤーには 1 つしかありません）。自動修正されないため、抜き取り確認してください。
• 目次の点線が表として検出されます。必要であれば、目次を手動で書き直してください。
• 複数ページにまたがる表は結合されません（各ページの断片にはそれぞれ独自のヘッダー行が残ります）。手動で結合してください。
• 斜めの透かしが重なった表のセルには、透かし文字の断片（dn、uFE など）が含まれることがあります。繰り返し行の除去処理で削除されるのは完全な行だけで、セル内の断片は対象外です。透かしの多い PDF では、セル単位での再構築（各セルの bbox 内にある透かし以外の span を収集）が必要です。
• 複雑なインフォグラフィック（画像内にテキストが密集しているもの）は画像のみとして出力されます。画像内のテキストを書き起こすには、このツールではなく VLM の処理が必要です。

CJK の太字の空白 — 理由と方法

DOCX はランレベルのスタイルを使用します（CJK テキストでは太字と通常のテキストの間にスペースがありません）。Markdown レンダラーが太字の境界を認識するには、** の前後に空白が必要です。

ルール：**content** の範囲に CJK 文字が含まれる場合、すでに空白がある場合や行頭・行末の場合を除き、両側にスペースを入れます。これにより、CJK の句読点や絵文字との隣接、混在するコンテンツに対応できます。

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

よくある問題

「利用可能な変換ツールがありません」

# 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 アダプターと、保存された出力の source-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 モードの詳細なドキュメント
• 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