html-to-pdf

HTML から PDF への変換

Puppeteer（Chrome ヘッドレス）を使用した、ピクセル単位で忠実な HTML から PDF への変換です。ヘブライ語、アラビア語、その他の RTL 言語を優れた精度でサポートし、方向を自動検出します。

Puppeteer を使用する理由

• ピクセル単位で忠実なレンダリング：実際の Chrome エンジンを使用します
• CSS3/HTML5 を完全サポート：Flexbox、Grid、カスタムフォント、背景
• JavaScript の実行：動的コンテンツをレンダリングします
• RTL の自動検出：ヘブライ語／アラビア語を検出して方向を設定します
• ウェブフォントのサポート：カスタムフォントを適切に読み込みます

自動フィット（組み込み、フラグ不要）

スクリプトがコンテンツのはみ出しを自動的に処理します。

• わずかなはみ出し（約18％まで） → ページに収まるようフォントサイズを自動的に縮小します
• 大量のコンテンツ → スマートな改ページルールを使って、複数ページにわたりきれいに配置します（見出し、テーブルの行、画像を途中で分割しません）
• ぴったり収まる場合 → 何もしません

これは PDF の生成ごとに自動実行されます。フラグは不要です。

重要：コンテンツを1ページに収める

html または body に背景を設定すると、ページが余分に生成されます！ 背景は代わりにコンテナ要素に設定してください。

@page { size: A4; margin: 0; }

html, body {
  width: 210mm;
  height: 297mm;
  margin: 0;
  padding: 0;
  overflow: hidden;
  /* NO background here! */
}

.container {
  width: 100%;
  height: 100%;
  padding: 20mm;
  box-sizing: border-box;
  background: linear-gradient(...); /* Background goes HERE */
}

ページが余分に生成される一般的な原因：

1. html/body の背景 - 代わりに必ず .container に設定してください
2. コンテンツのはみ出し - overflow: hidden を使用してください
3. コンテンツをはみ出させるマージン／パディング

ヒント：

• それでもコンテンツがはみ出す場合は、--scale=0.75 --margin=0 を使用してください
• 横向きの場合は、--landscape を使用してください

セットアップ（初回のみ）

初めて使用する前に、依存関係をインストールしてください。

cd ~/.claude/skills/html-to-pdf && npm install

すぐに使う

ローカルの HTML ファイルを変換：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js input.html output.pdf

URL を PDF に変換：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js https://example.com page.pdf

RTL を強制したヘブライ語文書：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js hebrew.html hebrew.pdf --rtl

HTML コンテンツをパイプで渡す：

echo "<h1>שלום עולם</h1>" | node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js - output.pdf --rtl

オプション一覧

オプション	説明	デフォルト
--format=<format>	ページ形式：A4、Letter、Legal、A3、A5	A4
--landscape	横向きを使用します	false
--margin=<value>	すべての余白を設定します（例：「20mm」、「1in」）	20mm
--margin-top=<value>	上余白	20mm
--margin-right=<value>	右余白	20mm
--margin-bottom=<value>	下余白	20mm
--margin-left=<value>	左余白	20mm
--scale=<number>	拡大縮小率 0.1～2.0	1
--background	背景のグラフィックを印刷します	true
--no-background	背景を印刷しません	-
--header=<html>	ヘッダー HTML テンプレート	-
--footer=<html>	フッター HTML テンプレート	-
--wait=<ms>	フォント／JS の待機時間	1000
--rtl	RTL 方向を強制します	自動検出
--expect-pages=<N>	想定ページ数（異なる場合は警告します）	1
--no-page-check	ページ数の警告を無効にします	-

はみ出しの自動検出

スクリプトは PDF の生成後にページ数を自動確認します。デフォルトでは1ページを想定し、出力がそれより多い場合は警告します。

⚠️  WARNING: PAGE OVERFLOW DETECTED!
   Expected: 1 page(s)
   Actual:   2 page(s)

   Fix: Reduce content, margins, or font sizes in HTML
   Use --no-page-check to disable this warning

使い方：

• デフォルト：1ページを想定し、はみ出した場合に警告します
• --expect-pages=3：3ページを想定します（複数ページの文書向け）
• --no-page-check：確認を完全に無効にします

注： pdfinfo のインストールが必要です（poppler-utils に含まれています）。利用できない場合、確認は通知なしでスキップされます。

例

基本的な変換：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js report.html report.pdf

カスタム余白を指定した Letter 形式：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js doc.html doc.pdf --format=Letter --margin=1in

ヘブライ語の請求書：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js invoice-he.html invoice.pdf --rtl

横向きのプレゼンテーション：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js slides.html slides.pdf --landscape --format=A4

余白なし（フルブリード）：

node ~/.claude/skills/html-to-pdf/scripts/html-to-pdf.js poster.html poster.pdf --margin=0

ヘブライ語／RTL のベストプラクティス

HTML でヘブライ語を最適にレンダリングするには：

1. lang 属性を設定：<html lang="he" dir="rtl">
2. UTF-8 を使用：<meta charset="UTF-8">
3. CSS の方向：body に direction: rtl; text-align: right; を追加します
4. フォント：ヘブライ語に対応したウェブフォント（Noto Sans Hebrew、Heebo、Assistant）を使用します

ヘブライ語 HTML 構造の例（1ページ）：

<!DOCTYPE html>
<html lang="he" dir="rtl">
<head>
  <meta charset="UTF-8">
  <link href="https://fonts.googleapis.com/css2?family=Heebo:wght@400;700&display=swap" rel="stylesheet">
  <style>
    @page { size: A4; margin: 0; }
    html, body {
      width: 210mm;
      height: 297mm;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    .container {
      width: 100%;
      height: 100%;
      padding: 20mm;
      box-sizing: border-box;
      font-family: 'Heebo', sans-serif;
      direction: rtl;
      text-align: right;
      background: #f5f5f5; /* Background on container, NOT body */
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>שלום עולם</h1>
    <p>זהו מסמך בעברית</p>
  </div>
</body>
</html>

重要：複数ページの PDF では必ず scale=1.0 を使用してください

複数ページのドキュメントでは、--scale に 1.0 未満を絶対に指定しないでください。 次の問題が発生します。

• コンテンツがずれる（ページの中央に配置されない）
• グリッドレイアウトで RTL テキストがはみ出したり、切れたりする
• ビューポート幅の計算が予測できなくなる

代わりに、CSS のフォントサイズや間隔を小さくして、scale=1.0 のままコンテンツを収めてください。

.page {
  width: 210mm;         /* Matches A4 exactly at scale=1.0 */
  height: 297mm;        /* Matches A4 exactly at scale=1.0 */
  padding: 8mm 10mm 12mm;
  page-break-after: always;
  position: relative;
  background: #f7f8fa;
  overflow: hidden;
  box-sizing: border-box;
}

scale=1.0 でコンテンツがはみ出す場合： scale ではなく、フォントサイズ（基本サイズを 10～11px に）、パディング、マージンを小さくしてください。これにより CSS と PDF の 1:1 の対応が保たれ、レイアウトの乱れをすべて解消できます。

色に関するヒント： 純白（#fff）の背景では、色付きのアクセントが目立たなくなります。#f7f8fa または #f8fafb を使うと、さりげないコントラストによって色が引き立ちます。

トラブルシューティング

フォントが正しく表示されない

• フォントの読み込み時間を増やすため、--wait=2000 を追加します
• @font-face または Google Fonts でフォントが読み込まれていることを確認します

ヘブライ語が左から右に表示される

• RTL 方向を強制するため、--rtl フラグを使用します
• HTML 要素に dir="rtl" を追加します

ページ区切りが機能しない

CSS のページ区切りプロパティを使用します。

.page-break { page-break-after: always; }
.no-break { page-break-inside: avoid; }

背景が表示されない

• --background が設定されていることを確認します（デフォルトは true です）
• 背景を除外する場合に限り、--no-background を使用します

コンテンツの自動調整（必須の検証）

重要：Claude は PDF を生成するたびに、必ず次の手順を実行してください。

1. Read ツールを使って PDF ファイルを読み込み、目視で確認します
2. 縦方向のはみ出し（空白ページ、次のページへのコンテンツのはみ出し）がないか確認します
3. 横方向のはみ出し（テキストが左右で切れていないか）がないか確認します
4. 問題が1つでも見つかった場合 → 修正して再生成します（最大 5 回まで）
5. 検証に合格してから、PDF をユーザーに提供します

これは任意ではありません。目視で確認せずに PDF を提供してはいけません。

確認する問題

問題	症状	修正方法
縦方向のはみ出し	ページ下部に空白がある、次のページにコンテンツが表示される	--scale を小さくする
横方向の切れ	テキストが左右の端で切れる	--margin を小さくし、HTML の幅を修正する
両方の問題	コンテンツが切れ、ページ数も増える	まず HTML の CSS を修正し、その後 scale を調整する

修正手順（最大 5 回）

1 回目： デフォルト設定

node scripts/html-to-pdf.js input.html output.pdf

2 回目： 縦方向にはみ出す場合 → scale を小さくする

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9

3 回目： 横方向で切れる場合 → マージンを小さくする

node scripts/html-to-pdf.js input.html output.pdf --scale=0.9 --margin=10mm

4 回目： まだ問題がある場合 → scale とマージンをさらに小さくする

node scripts/html-to-pdf.js input.html output.pdf --scale=0.8 --margin=5mm

5 回目： まだ解決しない場合 → HTML の CSS を修正します。

/* Add to HTML to prevent horizontal overflow */
.container {
  width: 100%;
  max-width: 100%;
  overflow-wrap: break-word;
  word-wrap: break-word;
  box-sizing: border-box;
}

5 回で停止してください — 適切な制約を設定して HTML を再生成します。

HTML の幅の修正（横方向に収めるために必須）

コンテンツが左右で切れる場合、HTML に次の設定が必須です。

html, body {
  width: 210mm;  /* A4 width */
  margin: 0;
  padding: 0;
  overflow: hidden;
}

.container {
  width: 100%;
  max-width: 100%;
  padding: 15mm;
  box-sizing: border-box;
  overflow-wrap: break-word;
}

検証チェックリスト

PDF を生成するたびに、次の項目を確認します。

• すべてのテキストが表示されている（端で切れていない）
• 不要な空白ページがない
• コンテンツがページを適切に埋めている
• セクション間に大きな空白がない

項目に1つでも不合格があれば、調整して再生成します（最大 5 回まで）。

技術的な注意事項

• レンダリングには Puppeteer と Chrome headless を使用します
• すべてのリソースが読み込まれるよう、networkidle0 まで待機します
• document.fonts.ready まで自動的に待機します
• 印刷スタイル用の @page CSS ルールをサポートします
• くっきりとレンダリングするため、デバイスのスケールファクターは 2 に設定されています