Pagefind で静的サイトに全文検索を追加する

静的サイトに全文検索を付けたいとき、外部の検索 SaaS に頼らなくても Pagefind が使える。ビルド済みの HTML を走査してインデックスを作り、クライアント側だけで検索が完結する。サーバーも API キーもいらない。

ビルドの後処理として組み込む

Pagefind は「ビルドされた HTML」を入力にする。つまり astro build の後に走らせる必要がある。package.json の build スクリプトをこう繋げておく。

{
  "scripts": {
    "build": "astro build && pagefind --site dist"
  }
}

これで dist/pagefind/ にインデックスと検索 UI のスクリプトが生成される。

検索ページを置く

検索ページ側では、生成された UI スクリプトを読み込んで初期化するだけでよい。

<link href="/pagefind/pagefind-ui.css" rel="stylesheet" />
<div id="search"></div>
<script is:inline src="/pagefind/pagefind-ui.js"></script>
<script is:inline>
  window.addEventListener('DOMContentLoaded', () => {
    new PagefindUI({ element: '#search', showSubResults: true });
  });
</script>

showSubResults: true にすると、記事内の見出し単位で結果が展開されて便利だ。

ハマりどころ: pnpm dev では動かない

一番の落とし穴がこれ。インデックスはビルド後処理で生成されるので、pnpm dev（開発サーバー）には dist/pagefind/ が存在しない。開発サーバーで検索を試すと当然エラーになり、「検索が壊れている」と誤解しがちだ。

検索の動作確認は、必ずビルドしてからプレビューする。

pnpm build && pnpm preview

本番の Cloudflare は pnpm run build でビルドするので、この点は問題にならない。ローカルで確認するときだけ気をつければよい。