weasyprint-pdf-creation

WeasyPrint による PDF 作成

概要

このスキルを使うと、ソース管理された HTML/CSS テンプレートから、洗練された PDF を作成できます。基本的なワークフローは次のとおりです。

HTML template + print CSS + data → WeasyPrint → PDF → QA → publish/share

対象は、新規作成する PDFです。請求書、レポート、提案書、概要書、明細書、1 ページの文書、印刷用ガイド、テンプレートベースのビジネス文書などが該当します。

既存の任意の PDF の編集や、JavaScript を多用したウェブページのキャプチャに、これをデフォルトで使用しないでください。以下の判断表を参照してください。

使用する場面

ユーザーから次の依頼があった場合に、このスキルを使用します。

• 請求書、レポート、提案書、概要書、契約書形式の文書、配布資料、印刷用 PDF を作成する
• HTML/CSS を使って再利用可能な PDF テンプレートを作成する
• Markdown のエクスポート標準より見栄えのよい PDF を生成する
• アーティファクト用の棚や静的ホストに、レビュー用の PDF プレビューを公開する
• デザインした文書が印刷/PDF レンダリング後も問題ないかテストする

次の場合は、このスキルを使用しないでください。

• 既存 PDF のテキストを編集する → nano-pdf/PyMuPDF を使用
• スキャン画像から OCR/テキスト抽出を行う → OCR/文書抽出ツールを使用
• スクリーンショットや JavaScript で描画されたダッシュボードを扱う → Playwright/Chromium を使用
• 生のプログラムによるベクター描画を行う → ReportLab/SVG/PyMuPDF を検討

判断表

必要なもの	ツール
テンプレートから新規作成するデザイン済みの請求書/レポート/文書	WeasyPrint
既存 PDF のテキスト編集	nano-pdf / PyMuPDF
JavaScript を多用したウェブページやダッシュボードの PDF 化	Playwright/Chromium
PDF の抽出/OCR	OCR/文書ツール
低レベルの PDF 加工/結合/分割	pikepdf / PyMuPDF

推奨リポジトリ構成

pdf-project/
  templates/
    invoice.html
    report.html
    proposal.html
    one-page-brief.html
    receipt.html
    statement.html
  styles/
    print.css
  data/
    sample-invoice.json
    sample-report.json
    sample-proposal.json
  scripts/
    render_pdf.py
    qa_pdf.py
  outputs/
    .gitkeep
  examples/
    index.html
    invoice.pdf
    invoice.png
  docs/
    pdf-qa.md
    template-rules.md
  fonts/
    README.md
  requirements.txt
  README.md

実行しやすく、見た目も上品なテンプレートを作成してください。

• セマンティック HTML
• 印刷優先の CSS
• 必須の JavaScript なし
• 可能な限りローカルのアセット/フォントを使用
• データの挿入とレイアウトを分離
• ソース管理されたサンプル JSON
• 決定論的な生成結果

インストール

Python venv

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python -m weasyprint --info

requirements.txt の最小構成：

weasyprint==68.1
Jinja2>=3.1
pypdf>=5.0

Debian/Ubuntu のネイティブ依存関係

ほとんどの最新の Debian/Ubuntu ホストでは、次のようにします。

sudo apt-get update
sudo apt-get install -y \
  python3-pip \
  libpango-1.0-0 \
  libpangoft2-1.0-0 \
  libharfbuzz-subset0 \
  fontconfig \
  fonts-dejavu-core

テンプレートのルール

CSS

@page と印刷メディアを意図的に使用してください。

@page { size: A4; margin: 0; }
@media print {
  body { background: white; }
  .page { width: 210mm; height: 297mm; overflow: hidden; }
  .no-print { display: none; }
}

次を推奨します。

• ページのキャンバスと主要な印刷間隔には mm を使用する
• 安定した文書レイアウトには CSS グリッド/テーブルを使用する
• 金額と ID には font-variant-numeric: tabular-nums を使用する
• 請求書の表には列幅を明示する
• 印鑑/バッジ/装飾要素のためのスペースを確保する
• IBAN、メールアドレス、ID などの長い文字列に折り返しルールを設ける

次の使用は避けるか、慎重に検証してください。

• コンテンツの近くでの絶対位置指定
• ブラウザー専用の未サポート CSS
• box-shadow、filter、mix-blend-mode などの凝った効果
• JavaScript のみで行うグラフ/レンダリング処理
• サンプルテキストが短い場合にしか収まらないコンテンツ

HTML

セマンティックなブロックと安定したクラスを使用してください。

<section class="page invoice">
  <header class="invoice-header">...</header>
  <section class="invoice-meta">...</section>
  <table class="line-items">...</table>
  <section class="payment-box">...</section>
</section>

長い値には、次を使用します。

.long-value { overflow-wrap: anywhere; }
.amount { white-space: nowrap; text-align: right; }

レンダリングスクリプトのパターン

レンダリングを再現可能かつテスト可能にするため、小さな Python スクリプトを使用してください。

from pathlib import Path
import argparse, json
from jinja2 import Environment, FileSystemLoader, select_autoescape
from weasyprint import HTML

parser = argparse.ArgumentParser()
parser.add_argument('--template', required=True)
parser.add_argument('--data', required=True)
parser.add_argument('--out', required=True)
args = parser.parse_args()

template_path = Path(args.template)
data = json.loads(Path(args.data).read_text())

env = Environment(
    loader=FileSystemLoader(str(template_path.parent)),
    autoescape=select_autoescape(['html', 'xml'])
)
html = env.get_template(template_path.name).render(**data)
Path(args.out).parent.mkdir(parents=True, exist_ok=True)
HTML(string=html, base_url=str(template_path.parent.resolve())).write_pdf(args.out)

QA チェックリスト

PDF の完成とする前に、次のすべてを実行してください。

1. WeasyPrint の警告を確認

python scripts/render_pdf.py --template templates/invoice.html --data data/sample-invoice.json --out outputs/invoice.pdf 2> outputs/weasyprint.log
test ! -s outputs/weasyprint.log

警告から、未サポートの CSS や壊れたアセットが見つかることがよくあります。意図的に問題がなく、その旨が記録されている場合を除き、修正してください。

2. PDF のメタデータ/ページを確認

pdfinfo outputs/invoice.pdf | grep -E 'Pages|Page size|PDF version'

A4 の想定値：

Page size: 595.276 x 841.89 pts (A4)

3. テキスト抽出のスモークテスト

pdftotext outputs/invoice.pdf - | grep -E 'Invoice|Total|Payment'

これにより、見えないテキスト、コンテンツの欠落、意図しない空白ページの多くを検出できます。

4. ブラウザーでプレビュー

HTML のプレビューを開き、コンソールエラーがないか確認してください。アーティファクト用の棚/静的ホスティングの場合：

artifact add-dir my-pdf-lab ./public --title "PDF Lab" --type site --tag artifact
curl -fsSI https://artifacts.example.com/artifacts/my-pdf-lab/

5. 見た目/重なりを確認

レンダリングした HTML/PDF を目視で確認してください。次の点を重点的に確認します。

• 合計金額と金額の列
• 支払い欄
• 長い ID/IBAN/メールアドレスのフィールド
• 印鑑/バッジ
• フッターの間隔
• ページ区切り
• ページ境界付近の表の行

ユーザーから重なりの報告があった場合、曖昧な返答で済ませないでください。ブラウザー/ビジョンで再確認し、詰まった箇所を再設計してください。

公開のパターン

レビュー用に、プレビューと PDF を含む静的フォルダーを公開します。

public/
  index.html
  invoice.html
  invoice.pdf
  report.html
  report.pdf

次に：

artifact add-dir pdf-lab public --title "PDF Lab" --type site --tag artifact
curl -fsSI https://artifacts.omarbenaidy.com/artifacts/pdf-lab/

別の環境を使用する場合は、GitHub Pages、Cloudflare Pages、Netlify、nginx、S3 など、任意の静的ホストを使用できます。

フォントに関するガイダンス

フォントはページ割りやはみ出しに影響します。再現可能な PDF を作成するには、次の点に注意してください。

• 明示的なフォントスタックを定義する
• 本番用フォントを同梱するか、インストールする
• レンダラーが macOS で動作する場合を除き、macOS 専用フォントに依存しない
• フォントを変更した後は、QA を再実施する
• 選定したフォントとライセンスを fonts/README.md に記載し、最新の状態に保つ

よくある落とし穴

1. ブラウザーの CSS サポートを WeasyPrint の CSS サポートと同じものとして扱う。 WeasyPrint は印刷用 CSS に優れていますが、Chrome と完全に同じではありません。早い段階で一度生成し、警告を確認してください。

2. 実際のコンテンツの上に装飾を絶対配置する。 スタンプ、図形、バッジのために、レイアウト内にスペースを確保する必要があります。支払金額、合計、フッターの上に重ねると、実データと重なります。

3. 単一行のフィールドに長い値を入れる。 IBAN、住所、メールアドレス、請求書参照番号には、overflow-wrap:anywhere または縦に並べるレイアウトが必要です。

4. 意図せず空白ページが追加される。 min-height:297mm にパディングやコンテンツを加えると、はみ出すことがあります。印刷モードでは height:297mm と調整したパディングを使い、pdfinfo でページ数を確認してください。

5. レンダラーのバージョンを固定しない。 レンダリング結果は WeasyPrint のバージョンによって変わることがあります。バージョンを固定し、アップグレード後はゴールデン PDF を再確認してください。

6. フォントを固定しない。 フォントが見つからない場合や異なるフォントが使われた場合、レイアウトが変わります。既知のフォントをインストールし、システム固有の書体に依存しないでください。

7. スクリーンショットだけで QA する。 スクリーンショットは補助的なものです。ログ、ページ数、抽出テキスト、ブラウザーコンソール、実際の PDF の有無を確認してください。

検証チェックリスト

• WeasyPrint のバージョンが固定されている
• ネイティブ依存関係とフォントがインストールされ、文書化されている
• レンダリングコマンドを再現可能な形で実行できる
• レンダリングログに予期しない警告がない
• pdfinfo のページ数とサイズが想定どおりである
• pdftotext で重要なコンテンツを確認できる
• ブラウザープレビューにコンソールエラーがない
• ビジュアル QA で合計、支払い、フッター、ページ区切りを確認している
• 公開が求められている場合、公開用／レビュー用リンクが 200 を返す