テーマ制作の注意点

前提：全員に同じHTMLが配られます

静的サイトでは、1つのURLにつき1つのファイルがあるだけです。誰がいつアクセスしても同じ中身が返ります。この前提から外れる作りは、そのままでは動きません。

最重要：リクエストごとに変わる値を出さない

これは見た目の問題ではなく、公開のたびに全ファイルが再転送される原因になります。

このプラグインは「前回とまったく同じ内容なら書き出さない」ことで転送量を抑えています。1文字でも毎回変わると、内容が実質同じでも別ファイルとみなされ、この仕組みが働きません。

出してはいけないもの	理由と対処
CSRFトークン	静的HTMLに焼き込んでも機能しません。CSRFトークンは閲覧者ごとのCookieと突き合わせて検証するものなので、全員に同じ値を配っても一致しません。静的化のときは出力しないようにしてください（下の見分け方を参照）。
キャッシュ対策の乱数	`style.css?1234567` のように毎回違う数値を付けるもの。ファイルの更新日時など、内容が変わったときだけ変わる値に置き換えてください。
生成日時・現在時刻	「最終更新: 2026/08/09 20:15」のような表示。日付までにするか、コンテンツの更新日時を使ってください。
ランダム表示	「おすすめをランダムに3件」のような表示。静的化すると、全員に同じ3件が固定で表示されます（毎回HTMLも変わります）。JavaScriptで表示するか、固定にしてください。
アクセスカウンタ	数えられません。外部サービスをJavaScriptで埋め込んでください。

静的化のためのアクセスを見分ける

このプラグインがページを取得するとき、X-Hat-Static-Engine: 1 というHTTPヘッダを付けています。テーマやプラグインの側でこれを見れば、「いまは静的化のための取得だ」と判断して出力を変えられます。

// 静的化のための取得なら、CSRFトークンを埋め込まない
$isStatic = $this->getRequest()->getHeaderLine('X-Hat-Static-Engine') !== '';
$token = $isStatic ? '' : $this->getRequest()->getAttribute('csrfToken');

毎回変わっていないか確かめる

cp static/staging/company/index.html /tmp/before.html
bin/cake hat_static_engine generate --url=/company/
bin/cake hat_static_engine work
diff /tmp/before.html static/staging/company/index.html

差分が出なければ問題ありません。出た場合は、その行が原因です。

リンクの書き方

項目	内容
内部リンク	自動で書き換わるので、普通に書いて構いません。CMSと同じホストの絶対URLはルート相対（`/news/`）へ、固定ページへのリンクは `.html` 付きへ、ページ送りはディレクトリ形式へ変換されます。
書き換わる属性	`href` / `src` / `action` の3つだけです。
JavaScriptの中のURL	書き換わりません。JavaScript の中に `fetch('/api/...')` のようにURLを書いている場合、静的サイトでは動きません。
data属性のURL	`data-href` などは書き換え対象外です（意図しない書き換えを避けるため）。JavaScriptで使う場合は注意してください。

フォーム

公開先にPHPが無ければ、フォームの送信先も動きません。次のどれかを選んでください。

方法	内容
外部サービスへ	Googleフォームなどへリンクを向けます。URLの読み替えを使えば、テーマを直さずにリンク先だけ差し替えられます。
CMS側へ送る	フォームの送信先だけをCMSのURL（絶対URL）にします。ただしCMSが外部から見える必要があります。CMSのアドレスが公開されることになる点に注意してください。
静的化しない	そのページだけ「URL除外パターン」で対象から外し、CMSで運用します。

ページ送り

baserCMS のページャは ?page=2 という形のリンクを出しますが、これは自動で /news/page/2/ へ書き換わります。テーマ側で特別な対応は要りません。

カテゴリ別・タグ別・日付別ページのページャが、カテゴリ名の落ちたURL（/news/archives?page=2）を出力する問題も、このプラグインが正しいURLへ復元します。

「先頭の数ページだけ作る」設定を使う場合は、テーマ側のページャも合わせてください。 作らないページへのリンクが残っていると、リンク切れになります。

確認の手順

1ページ生成して中身を見る
書き出されたHTMLをエディタで開き、CMSのURLが残っていないか、フォームの送信先がどうなっているかを確認します。
2回生成して差分を取る
上の diff の手順で、毎回変わる値が無いか確認します。
公開先をブラウザで開く
ブラウザの開発者ツールで、404になっているファイルが無いか確認します。