wkhtmltopdf からの移行

wkhtmltopdf で PDF を生成しているアプリケーションを Printgraph に移行する際の、オプションの対応・CSS の違い・コード例をまとめました。

wkhtmltopdf は HTML ファイルや URL をコマンドのたびに渡して PDF に変換しますが、Printgraph はダッシュボードに登録したテンプレート（HTML + LiquidJS）を templateId で指定し、見出しの請求書番号や明細のような可変部分だけを params として渡すモデルです。レイアウトの HTML / CSS は事前にテンプレートとして保存しておき、API 呼び出しのたびに送る必要はありません。詳しいリクエスト仕様はPDF を生成するを参照してください。

コマンドオプションの対応

wkhtmltopdf のコマンドラインオプションは、Printgraph では API のパラメータかテンプレートの CSS に置き換わります。

wkhtmltopdf	Printgraph での対応
`--page-size`	API の `format`（既定は `A4`。`Letter` / `Legal` / `Tabloid` / `Ledger` / `A0`〜`A6` に対応）。任意の寸法にしたい場合はテンプレートの CSS で `@page { size: ... }` を指定してください（`format` より優先されます）。
`--orientation Landscape`	対応するパラメータはありません。テンプレートの CSS で `@page { size: A4 landscape; }` を指定してください。
`-T` / `-B` / `-L` / `-R`（余白）	対応するパラメータはありません。テンプレートの CSS で `@page { margin: ...; }` を指定してください。
`--header-html` / `--footer-html`	対応するパラメータはありません。Chromium はページをまたぐ表の `<thead>` / `<tfoot>` を改ページごとに繰り返す挙動があるため、テンプレートを表で組んでヘッダー・フッターを `thead` / `tfoot` に置くと近い見た目になる場合があります。
`--dpi`	対応するパラメータはなく、指定の必要もありません。レンダリングに使う Chromium はテキストや図形をベクターで出力するため、DPI に依存しません。画像を鮮明にしたい場合は、元の画像自体の解像度を上げてください。
`--zoom`	対応するパラメータはありません。テンプレートの CSS でフォントサイズや単位を調整してください。
`--enable-javascript` / `--javascript-delay` / `--window-status`	対応するパラメータはありません。テンプレートの `<script>` はサーバー側のサニタイズで取り除かれ、JavaScript は実行されません。動的な値は API の `params` として渡し、LiquidJS のテンプレート構文で展開してください。
入力の HTML ファイル / URL	テンプレートをダッシュボードに登録し、`templateId` を指定します。可変部分は `params` として渡してください。
`--background`（既定で有効）	Printgraph も背景色・背景画像は常に出力します。

CSS・レンダリングの違い

wkhtmltopdf は古い Qt WebKit でレンダリングしますが、Printgraph は最新の Chromium（Playwright）を使います。モダンな CSS がそのまま使えるようになる一方、挙動が変わる点もあります。

flexbox / grid がそのまま使える

wkhtmltopdf 向けに書いていた display: -webkit-box やテーブルレイアウトのハックは不要です。flexbox / grid をそのまま使えます。

page-break は break に置き換え推奨

page-break-before / page-break-after / page-break-inside は Chromium でも解釈されますが、後継の break-before / break-after / break-inside への置き換えを推奨します。

/* Before（wkhtmltopdf 向け） */
.section {
  page-break-before: always;
}

/* After */
.section {
  break-before: page;
}

@page の size / margin が有効

テンプレートの CSS に書いた @page の size と margin が実際の用紙サイズ・余白に反映されます。用紙の向きを変える例、余白を指定する例は次のとおりです。

@page {
  size: A4 landscape;
}

@page {
  margin: 20mm 15mm;
}

@page {
  size: 100mm 50mm;
  margin: 0;
}

ページをまたぐ表のヘッダー・フッター

<thead> と <tfoot> を使った表は、改ページで分かれても見出し行・末尾行が繰り返されることがあります。明細が複数ページにわたるテンプレートで活用できます。

<table>
  <thead>
    <tr><th>商品名</th><th>単価</th><th>数量</th></tr>
  </thead>
  <tbody>
    {% for item in items %}
    <tr>
      <td>{{ item.name }}</td>
      <td>¥{{ item.price }}</td>
      <td>{{ item.quantity }}</td>
    </tr>
    {% endfor %}
  </tbody>
  <tfoot>
    <tr><td colspan="3">以下つづく</td></tr>
  </tfoot>
</table>

フォント

サーバーに入っている和文フォントは Noto Sans JP のみです。serif や明朝体を指定しても、ゴシック体（Noto Sans JP）で描画されます。明朝体など別のフォントが必要な場合は、@font-face でフォントデータを埋め込んでください。外部フォントの URL を指定することもできますが、読み込みの完了を待ってから PDF を生成するため、読み込みに時間がかかるフォントは生成が遅くなります。

body {
  font-family: serif;
}

@font-face {
  font-family: "MinchoEmbedded";
  src: url(data:font/woff2;base64,...) format("woff2");
}

body {
  font-family: "MinchoEmbedded", "Noto Sans JP", sans-serif;
}

-webkit- 接頭辞は基本的に不要

wkhtmltopdf（Qt WebKit）向けに書いていた -webkit- 接頭辞付きの CSS プロパティは、標準プロパティに対応している場合はほとんど不要になります。

コードの移行例

PHP・JavaScript（Node.js）・curl それぞれで、wkhtmltopdf を呼び出すコードを Printgraph に置き換える例を示します。

PHP

Before（knp-snappy で wkhtmltopdf を呼び出す）

<?php

use Knp\Snappy\Pdf;

$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');

$pdf = $snappy->getOutputFromHtml($html, [
    'page-size' => 'A4',
    'margin-top' => '20mm',
]);

file_put_contents('invoice.pdf', $pdf);

After

用紙サイズ・余白はテンプレートの @page で指定するため、SDK 呼び出しでは指定しません。

<?php

use Printgraph\PhpSdk\Api\Pdf\Generator\GenerateRequest;
use Printgraph\PhpSdk\Client\ClientFactory;
use Printgraph\PhpSdk\Printgraph;

require 'vendor/autoload.php';

$printgraph = new Printgraph(
    ClientFactory::createHttpClient(getenv('PRINTGRAPH_TOKEN'))
);

$request = new GenerateRequest(
    'YOUR_TEMPLATE_ID',
    [
        'invoiceNumber' => 'INV-001',
        'customerName' => '山田太郎',
        'amount' => 10000,
    ]
);

$response = $printgraph->pdf()->generate($request)->expect(
    new \RuntimeException('PDF の生成に失敗しました')
);

file_put_contents('invoice.pdf', $response->getContents());

PHP SDK の詳しい使い方はPHP SDKを参照してください。

JavaScript（Node.js）

Before（child_process で wkhtmltopdf を呼び出す）

import { execFile } from 'node:child_process';

execFile(
  'wkhtmltopdf',
  ['--page-size', 'A4', '-T', '20mm', 'input.html', 'invoice.pdf'],
  (error) => {
    if (error) throw error;
  },
);

After

用紙サイズ・余白はテンプレートの @page で指定するため、SDK 呼び出しでは指定しません。

import { Printgraph } from "@printgraph/js-sdk";
import fs from "node:fs";

const client = new Printgraph(process.env.PRINTGRAPH_TOKEN);

const buf = await client.generatePDF({
  templateId: "YOUR_TEMPLATE_ID",
  params: {
    invoiceNumber: "INV-001",
    customerName: "山田太郎",
    amount: 10000,
  },
});

fs.writeFileSync("invoice.pdf", Buffer.from(buf));

JavaScript SDK の詳しい使い方はJavaScript SDKを参照してください。

curl

Before

wkhtmltopdf --page-size A4 -T 20mm input.html output.pdf

After（余白の -T 20mm はテンプレートの @page に移します）

curl -X POST https://api.printgraph.jp/v1/pdf/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "YOUR_TEMPLATE_ID",
    "params": {
      "invoiceNumber": "INV-001",
      "customerName": "山田太郎",
      "amount": 10000
    },
    "format": "A4"
  }' \
  --output output.pdf

Claude Code や Codex に移行を任せる

Printgraph はMCP サーバーを提供しています。Claude Code や Codex のようなコーディングエージェントに Printgraph を MCP で接続すると、エージェントがリポジトリにある wkhtmltopdf 用の HTML を読み、テンプレートに書き換え、そのまま Printgraph に登録するところまでを任せられます。ダッシュボードに HTML を貼り付け直す必要はありません。

接続方法はMCP 連携を参照してください。Claude Code はコマンド 1 つで登録できます。Codex など、そのほかのリモート MCP サーバーに対応したエージェントでも、同じ URL を登録すれば使えます。

接続したら、エージェントに次のように依頼します。

templates/invoice.html は wkhtmltopdf 用の請求書テンプレートです。
これを Printgraph のテンプレートに移行してください。

- 呼び出しごとに変わる値（請求書番号・宛先・明細）を Liquid の変数にする
- wkhtmltopdf に渡している --page-size / -T などのオプションを @page に移す
- <script> に頼っている箇所は、値を params で受け取る形に書き換える
- できたら Printgraph に「請求書」という名前でテンプレートを作成する

エージェントは MCP の create_template でテンプレートを作成し、直したいときは create_template_version で新しいバージョンを追加します。作成されたテンプレートの ID を、上のコード例の templateId に使ってください。

MCP からは PDF を生成できません。テンプレートの作成・編集は MCP で、PDF の生成はこれまでどおり API キーを使った API / SDK で行ってください。

移行チェックリスト

wkhtmltopdf に渡している HTML / CSS を洗い出す
請求書番号や宛先、明細のように呼び出しごとに変わる部分を LiquidJS の変数（{{ variable }}）に置き換え、Printgraph のテンプレートとして登録する
--page-size / --orientation / 余白オプションを、テンプレートの CSS の @page に置き換える
--enable-javascript などに依存していた動的な値を、呼び出し側で計算してから params として渡す形に変える
明朝体など Noto Sans JP 以外のフォントを使っていないか確認し、必要なら @font-face で埋め込む
page-break-* を使っている箇所を break-* に置き換える（任意）
ヘッダー・フッターを使っていた箇所は、thead / tfoot での再現を検討する
API キーを発行する
wkhtmltopdf を呼び出していたコードを、API 呼び出しまたは SDK の呼び出しに置き換える
生成された PDF を、移行前の出力と見比べて確認する

wkhtmltopdf からの移行

wkhtmltopdf で PDF を生成しているアプリケーションを Printgraph に移行する際の、オプションの対応・CSS の違い・コード例をまとめました。

コマンドオプションの対応

wkhtmltopdf のコマンドラインオプションは、Printgraph では API のパラメータかテンプレートの CSS に置き換わります。

wkhtmltopdf	Printgraph での対応
`--page-size`	API の `format`（既定は `A4`。`Letter` / `Legal` / `Tabloid` / `Ledger` / `A0`〜`A6` に対応）。任意の寸法にしたい場合はテンプレートの CSS で `@page { size: ... }` を指定してください（`format` より優先されます）。
`--orientation Landscape`	対応するパラメータはありません。テンプレートの CSS で `@page { size: A4 landscape; }` を指定してください。
`-T` / `-B` / `-L` / `-R`（余白）	対応するパラメータはありません。テンプレートの CSS で `@page { margin: ...; }` を指定してください。
`--header-html` / `--footer-html`	対応するパラメータはありません。Chromium はページをまたぐ表の `<thead>` / `<tfoot>` を改ページごとに繰り返す挙動があるため、テンプレートを表で組んでヘッダー・フッターを `thead` / `tfoot` に置くと近い見た目になる場合があります。
`--dpi`	対応するパラメータはなく、指定の必要もありません。レンダリングに使う Chromium はテキストや図形をベクターで出力するため、DPI に依存しません。画像を鮮明にしたい場合は、元の画像自体の解像度を上げてください。
`--zoom`	対応するパラメータはありません。テンプレートの CSS でフォントサイズや単位を調整してください。
`--enable-javascript` / `--javascript-delay` / `--window-status`	対応するパラメータはありません。テンプレートの `<script>` はサーバー側のサニタイズで取り除かれ、JavaScript は実行されません。動的な値は API の `params` として渡し、LiquidJS のテンプレート構文で展開してください。
入力の HTML ファイル / URL	テンプレートをダッシュボードに登録し、`templateId` を指定します。可変部分は `params` として渡してください。
`--background`（既定で有効）	Printgraph も背景色・背景画像は常に出力します。

CSS・レンダリングの違い

flexbox / grid がそのまま使える

wkhtmltopdf 向けに書いていた display: -webkit-box やテーブルレイアウトのハックは不要です。flexbox / grid をそのまま使えます。

page-break は break に置き換え推奨

/* Before（wkhtmltopdf 向け） */
.section {
  page-break-before: always;
}

/* After */
.section {
  break-before: page;
}

@page の size / margin が有効

@page {
  size: A4 landscape;
}

@page {
  margin: 20mm 15mm;
}

@page {
  size: 100mm 50mm;
  margin: 0;
}

ページをまたぐ表のヘッダー・フッター

<table>
  <thead>
    <tr><th>商品名</th><th>単価</th><th>数量</th></tr>
  </thead>
  <tbody>
    {% for item in items %}
    <tr>
      <td>{{ item.name }}</td>
      <td>¥{{ item.price }}</td>
      <td>{{ item.quantity }}</td>
    </tr>
    {% endfor %}
  </tbody>
  <tfoot>
    <tr><td colspan="3">以下つづく</td></tr>
  </tfoot>
</table>

フォント

body {
  font-family: serif;
}

@font-face {
  font-family: "MinchoEmbedded";
  src: url(data:font/woff2;base64,...) format("woff2");
}

body {
  font-family: "MinchoEmbedded", "Noto Sans JP", sans-serif;
}

-webkit- 接頭辞は基本的に不要

wkhtmltopdf（Qt WebKit）向けに書いていた -webkit- 接頭辞付きの CSS プロパティは、標準プロパティに対応している場合はほとんど不要になります。

コードの移行例

PHP・JavaScript（Node.js）・curl それぞれで、wkhtmltopdf を呼び出すコードを Printgraph に置き換える例を示します。

PHP

Before（knp-snappy で wkhtmltopdf を呼び出す）

<?php

use Knp\Snappy\Pdf;

$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');

$pdf = $snappy->getOutputFromHtml($html, [
    'page-size' => 'A4',
    'margin-top' => '20mm',
]);

file_put_contents('invoice.pdf', $pdf);

After

用紙サイズ・余白はテンプレートの @page で指定するため、SDK 呼び出しでは指定しません。

<?php

use Printgraph\PhpSdk\Api\Pdf\Generator\GenerateRequest;
use Printgraph\PhpSdk\Client\ClientFactory;
use Printgraph\PhpSdk\Printgraph;

require 'vendor/autoload.php';

$printgraph = new Printgraph(
    ClientFactory::createHttpClient(getenv('PRINTGRAPH_TOKEN'))
);

$request = new GenerateRequest(
    'YOUR_TEMPLATE_ID',
    [
        'invoiceNumber' => 'INV-001',
        'customerName' => '山田太郎',
        'amount' => 10000,
    ]
);

$response = $printgraph->pdf()->generate($request)->expect(
    new \RuntimeException('PDF の生成に失敗しました')
);

file_put_contents('invoice.pdf', $response->getContents());

PHP SDK の詳しい使い方はPHP SDKを参照してください。

JavaScript（Node.js）

Before（child_process で wkhtmltopdf を呼び出す）

import { execFile } from 'node:child_process';

execFile(
  'wkhtmltopdf',
  ['--page-size', 'A4', '-T', '20mm', 'input.html', 'invoice.pdf'],
  (error) => {
    if (error) throw error;
  },
);

After

用紙サイズ・余白はテンプレートの @page で指定するため、SDK 呼び出しでは指定しません。

import { Printgraph } from "@printgraph/js-sdk";
import fs from "node:fs";

const client = new Printgraph(process.env.PRINTGRAPH_TOKEN);

const buf = await client.generatePDF({
  templateId: "YOUR_TEMPLATE_ID",
  params: {
    invoiceNumber: "INV-001",
    customerName: "山田太郎",
    amount: 10000,
  },
});

fs.writeFileSync("invoice.pdf", Buffer.from(buf));

JavaScript SDK の詳しい使い方はJavaScript SDKを参照してください。

curl

Before

wkhtmltopdf --page-size A4 -T 20mm input.html output.pdf

After（余白の -T 20mm はテンプレートの @page に移します）

curl -X POST https://api.printgraph.jp/v1/pdf/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "YOUR_TEMPLATE_ID",
    "params": {
      "invoiceNumber": "INV-001",
      "customerName": "山田太郎",
      "amount": 10000
    },
    "format": "A4"
  }' \
  --output output.pdf

Claude Code や Codex に移行を任せる

接続したら、エージェントに次のように依頼します。

templates/invoice.html は wkhtmltopdf 用の請求書テンプレートです。
これを Printgraph のテンプレートに移行してください。

- 呼び出しごとに変わる値（請求書番号・宛先・明細）を Liquid の変数にする
- wkhtmltopdf に渡している --page-size / -T などのオプションを @page に移す
- <script> に頼っている箇所は、値を params で受け取る形に書き換える
- できたら Printgraph に「請求書」という名前でテンプレートを作成する

MCP からは PDF を生成できません。テンプレートの作成・編集は MCP で、PDF の生成はこれまでどおり API キーを使った API / SDK で行ってください。

移行チェックリスト

wkhtmltopdf に渡している HTML / CSS を洗い出す
請求書番号や宛先、明細のように呼び出しごとに変わる部分を LiquidJS の変数（{{ variable }}）に置き換え、Printgraph のテンプレートとして登録する
--page-size / --orientation / 余白オプションを、テンプレートの CSS の @page に置き換える
--enable-javascript などに依存していた動的な値を、呼び出し側で計算してから params として渡す形に変える
明朝体など Noto Sans JP 以外のフォントを使っていないか確認し、必要なら @font-face で埋め込む
page-break-* を使っている箇所を break-* に置き換える（任意）
ヘッダー・フッターを使っていた箇所は、thead / tfoot での再現を検討する
API キーを発行する
wkhtmltopdf を呼び出していたコードを、API 呼び出しまたは SDK の呼び出しに置き換える
生成された PDF を、移行前の出力と見比べて確認する