pdf-to-html

PDF から HTML へ

PDF を、画像、表、グラフ、読み取り順序を保持した、読みやすい単一の自己完結型 HTML ファイルに変換します。図をすべて所定の位置に保ったまま、翻訳することもできます。

パイプラインは 抽出 → 確認 →（翻訳）→ 構築 → 検証 です。忠実性を実際に確保するのは、途中の「確認」と最後の「検証」のステップです。PDF は単なるテキストストリームではなくレイアウトなので、構築前にレンダリングされたページを読み、納品前にレンダリングされた HTML を確認します。

このスキルはインラインで実行されます（context: fork は使用しません）。翻訳では動的ワークフローをオーケストレーションするため、サブエージェントからワークフローを起動することはできません。

使用する場合／しない場合

• 目標が PDF を HTML／ウェブページとして読むこと、PDF をスタイル付き HTML ドキュメントに変換すること、または図表を保ったまま PDF を別の言語に翻訳することであれば、使用してください。
• プレーンな Markdown テキスト（スタイルなし、図は任意）が必要な場合は、代わりに doc-to-markdown を使用してください。
• 逆方向（Markdown → PDF）の場合は、代わりに pdf-creator を使用してください。

対応しないこと

• スキャン画像のみの PDF（テキストレイヤーなし）：まず OCR（例：ocrmypdf）を実行してから、これを使用してください。
• 複雑な複数列の表：セルのテキストは保持され読み取れますが、列の配置がテキストの流れに平坦化される場合があります。PyMuPDF は表をグリッドではなくテキストブロックとして読み取るため、罫線は失われます。PDF 内で画像になっている表は、画像として保持されます。表のグリッド構造が重要な場合は、doc-to-markdown を使用する（pandoc が実際の表を再構築します）か、そのページを別途変換してください。
• ピクセル単位で完全に一致する複製：出力は画像と読み取り順序を保つ、すっきりとしたリフロー形式であり、元のページレイアウトを 1 対 1 で複製するものではありません。
• 書き換え：翻訳してレイアウトし直しますが、要約や TL;DR の追加、論評は行いません。忠実性が重要です（以下の「忠実性」を参照）。

依存関係

uv（インライン依存関係を使用して Python を実行）、Google Chrome または Chromium（視覚的な検証用）。Python パッケージは uv run --with で導入されます：PyMuPDF、Pillow、numpy。Chrome と uv 以外に、事前インストールは不要です。

ワークフロー

このチェックリストをコピーし、作業しながらチェックを付けてください：

- [ ] 1. Extract structure + render pages   (extract_pdf.py)
- [ ] 2. Read pages/*.png — SEE the layout, find content vs decorative images
- [ ] 3. (only if translating) run the translation workflow
- [ ] 4. Build the single-file HTML          (build_html.py)
- [ ] 5. Verify visually                      (verify_render.py → Read every segment)
- [ ] 6. Deliver the .html

1. 抽出

uv run --with pymupdf python scripts/extract_pdf.py input.pdf

input-build/ に structure.json（フォントサイズを含むテキストブロックと、decorative のフラグが付いた画像ブロック）、images/、および pages/（ページごとに PNG 1 枚）を出力します。

2. 構築前に確認

input-build/pages/*.png を読みます。この手順は省略できません。実際のレイアウトを確認し、どの画像がコンテンツでどれが装飾なのかを見分け、表やグラフを特定する必要があります。長い PDF ならすべてのページを読み、短い PDF ならすぐに終わります。また、ドキュメントを十分に理解し、適切に翻訳するための工程でもあります。

3. 翻訳（任意）

ユーザーが別の言語を指定した場合にのみ実施します。references/translation_workflow.md を読み、手順に従ってください。動的ワークフローでページを並列に翻訳し、データグラフにキャプションを付け、用語を調整します。ステップ 4 で使用する 2 つのオーバーレイファイル（units.json、caps.json）が生成されます。1 ページを超える内容をインラインで手作業で翻訳しないでください。このワークフローを使うと用語の一貫性を保て、はるかに速く作業できます。

4. 構築

# original-language HTML
uv run --with Pillow python scripts/build_html.py input-build/structure.json --out output.html

# translated HTML (overlays from step 3)
uv run --with Pillow python scripts/build_html.py input-build/structure.json --out output.html \
    --translation input-build/units.json --captions input-build/caps.json --lang zh-CN

build_html.py はデータ駆動型です。フォントサイズから見出しレベルを推定し（最も一般的なサイズを本文とし、それより大きいサイズを h3／h2／h1 に割り当てます）、装飾画像を除外し、コンテンツ画像を圧縮された base64 としてインライン化して、1 つのポータブルなファイルにまとめます。特定のドキュメントに合わせた手動調整は行いません。特定の PDF の構造が特殊な場合（例：複数列、サイドバー、サイズのヒューリスティック判定を誤る図）は、スクリプトを読み、調整してください。短いスクリプトなので、ドキュメントごとに編集することを想定しています。

5. 見た目を確認する（必須）

uv run --with Pillow --with numpy python scripts/verify_render.py output.html

次に、すべての seg-*.png を読み込み、フォントが正しく表示されているか（文字化けした豆腐がないか）、表や図が切れていないか、見出しやリストの見た目が正しいか、想定される画像がすべて含まれているかを確認します。テキストが正しくても、レンダリングが正しいとは限りません（failure_cases #7）。問題がなくなるまで修正して再確認してください。

構造を簡単に照合するのも有効ですが、出現回数を正しく数えてください。 grep -o '<figure>' output.html | wc -l を使用し、grep -c は使用しないでください（failure_cases #1）。

6. 納品する

単一の .html ファイルを納品します。自己完結型（画像は埋め込み済み）なので、ダブルクリックで開け、ファイルが欠落する心配もありません。

スクリプト

スクリプト	実行方法	用途
scripts/extract_pdf.py	uv run --with pymupdf	PDF → structure.json + images/ + ページのレンダリング
scripts/build_html.py	uv run --with Pillow	structure.json（＋任意の翻訳／キャプション）→ 単一ファイルの HTML
scripts/verify_render.py	uv run --with Pillow --with numpy	ヘッドレス Chrome でレンダリング → 読みやすい PNG セグメント

忠実性（翻訳前に読むこと）

納品物は信頼性が高そうに見えるため、内容の誤りは見た目の悪さよりも重大です。 譲れないルールと、過去に問題が起きた具体的な事例は references/failure_cases.md に記載されています。最も注意が必要なのは、実在の人物に推測で翻訳した名前を付けず、数字や固有名詞はすべて原文どおりに転記することです（failure_cases #6）。翻訳を実行する前にこのファイルを読み、実行前には必ず目を通してください。

次のステップ

HTML を作成した後、自然な次の作業を提案します。

Conversion complete: output.html (single self-contained file).

Options:
A) Make a PDF of it — run /daymade-docs:pdf-creator if you want a print/share copy (Recommended if they need to send it)
B) Extract the text as Markdown instead — run /daymade-docs:doc-to-markdown (if they wanted editable text, not a reading page)
C) No thanks — the HTML is what I wanted