markdown-pdf-layout

Markdown を CSS 付き HTML と PDF に変換し、要素単位で改ページ位置を調整する小さな CLI です。 nlp_preprocessing の task 9 で作られ、task 10 で汎用化された PDF renderer を独立させたものです。

現在できること

• Markdown を印刷用 HTML に変換
• Chrome / Chromium の headless print でPDFを生成
• 任意の CSS ファイルを --css で適用
• 見出し、図、表、コードへ安定した source ID を付与
• JSON で指定した要素の直前改ページ、要素内の分割抑止
• 孤立見出し、図とキャプションの分離、短い表・コードの分断、余白超過を検査
• 入力 Markdown を変更しない非破壊ビルド
• CLIに依存しない公開Python Core API
• A3/A4/A5/B4/B5/Letter/Legal、余白、フォント、出力名の設定
• ローカル専用の Web preview（ブラウザでの編集・プレビュー・PDF生成、詳細は下記）

必要なもの

• Python 3.11 以上
• Google Chrome、Chromium、または Chromium Browser
• ページ画像も生成する場合は pdftoppm（Poppler）

インストール

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'

使い方

まず HTML と source registry を生成します。

mdpdf report.md --html-only

_build/report.source_registry.json にある ID を確認し、layout.json を編集します。完全な例は layout.example.json、Python APIは docs/core_api.md を参照してください。

{
  "layout": {
    "page_break_before": ["heading-3"],
    "keep_together": ["table-3-1"]
  },
  "page": {"size": "A4", "margin_top": "18mm"},
  "output_name": "report.pdf"
}

PDF 生成とレイアウト検査を実行します。

mdpdf report.md --config layout.json

独自 CSS を使う場合:

mdpdf report.md --config layout.json --css my-report.css --output-dir dist

生成物は既定で Markdown と同じディレクトリに置かれます。

• _build/<name>.render.html
• _build/<name>.source_registry.json
• <name>.pdf
• layout_check.json

レイアウト検査は PDF の文字・画像座標に基づくヒューリスティックです。PASS は視覚確認が不要という意味ではありません。 対応環境と既知の制限は docs/supported_environments.md にまとめています。

Web preview（ローカル専用 MVP）

Markdown のアップロード／貼り付け、リアルタイムプレビュー、要素ごとの改ページ・分割抑止トグル、CSS 編集、印刷設定（用紙・余白・フォント・出力名）、layout JSON の import/export、実 Chrome による PDF ダウンロードをブラウザから行える FastAPI + static JS の Web UI です。CLI を subprocess で呼ばず、Core API（prepare_document() / write_document()）を直接使います。

インストールと起動:

pip install -e '.[dev,web]'
mdpdf-web

http://127.0.0.1:8000/ をブラウザで開きます。

[!WARNING] ローカル専用 MVP です。 認証、CSRF/origin 対策、レート制限、プロセス分離が無いため、信頼できる単一操作者がローカルで使う前提でのみ動作します。ネットワーク越しに公開したり、複数テナントへ提供したりしないでください。raw HTML、外部/ローカルリソース読み込み、unsafe な CSS（url(), @import, expression(), javascript:, file:, behavior:, backslash escape）は拒否されますが、これは多層防御であり公開デプロイに対応済みという意味ではありません。設計判断とセキュリティ境界の詳細は docs/adr/0001-web-preview-mvp.md と docs/web_security.md を参照してください。

今後の拡張候補

• PDF ページサムネイルのプレビュー統合（正確なページ境界の可視化）
• 複数ファイル／画像アセットのアップロード対応
• 設定・プレビュー状態の保存（現状は永続化なし、リクエストごとに破棄）

出自

コア実装は task 10 の tools/pdf_renderer から抽出しています。task 9 固有のレポート名、出力パス、実験用 CSS を除去し、任意の Markdown を受け取る CLI に変更しました。

License

MIT