Pagefind で GitHub Pages に検索機能を追加する

1Pagefind 設定ファイル

リポジトリのルートに pagefind.yml を配置します。index.html と同じフォルダ内の HTML ファルを対象にインデックスを生成します。

pagefind.yml YAML

# ═══════════════════════════════════════════════════════════════
#  Pagefind Configuration for GitHub Pages
# ═══════════════════════════════════════════════════════════════

# ビルド済みHTMLの出力ディレクトリ（GitHub Pagesの公開フォルダ）
site: "."

# インデックス対象ファイル
glob: "**/*.html"

# 検索バンドルの出力先
output_subdir: "pagefind"

# ナビゲーション・フッター等を除外
exclude_selectors:
  - "nav"
  - "footer"
  - "header"
  - ".sidebar"
  - "[data-pagefind-ignore]"

# GitHub Pagesでは /path/ 形式のURLが基本なので index.html を省略
keep_index_url: false

# 日本語サイトの場合は以下を有効化
# force_language: "ja"

Tip

GitHub Pages の公開フォルダが docs/ の場合は、site: "docs" に変更してください。

2GitHub Actions ワークフロー

プッシュ時に自動で Pagefind インデックスを生成し、GitHub Pages にデプロイするワークフローです。

.github/workflows/pagefind.yml YAML

name: Build and Deploy Pagefind Index

on:
  push:
    branches: [main, master]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Pagefind
        run: npm install -g pagefind

      - name: Generate Pagefind Index
        run: pagefind --site "." --output-subdir "pagefind"

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "."

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3検索UIを埋め込む HTML

index.html に Pagefind の検索UIを組み込むコードです。CSS と JavaScript を読み込むだけで、検索モーダルが自動的に表示されます。

index.html HTML

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>Document Search</title>
  <link href="/pagefind/pagefind-ui.css" rel="stylesheet">
</head>
<body>
  <h1>README Search</h1>
  <div id="search"></div>

  <script src="/pagefind/pagefind-ui.js"></script>
  <script>
    new PagefindUI({
      element: "#search",
      showImages: false
    });
  </script>
</body>
</html>

4設定オプション一覧

よく使う pagefind.yml の設定項目をまとめました。

設定項目	型	説明
`site`	string	ビルド済みHTMLのルートディレクトリ
`glob`	string	インデックス対象ファイルのパターン
`output_subdir`	string	検索バンドルの出力先（デフォルト: `pagefind`）
`exclude_selectors`	array	インデックスから除外するCSSセレクタ
`root_selector`	string	インデックスの起点要素（デフォルト: `html`）
`force_language`	string	言語を強制指定（例: `ja`, `en`）
`keep_index_url`	boolean	URL に `index.html` を保持する
`write_playground`	boolean	Playground を検索バンドルに含める

5導入手順

pagefind.yml を作成
リポジトリのルートに配置し、site の値を公開フォルダに合わせて調整します。
GitHub Actions ワークフローを作成
.github/workflows/pagefind.yml にワークフローを配置します。GitHub Pages のデプロイ設定も有効化してください。
index.html に検索UIを埋め込む
CSS と JS を読み込み、<div id="search"> を配置します。
コミットしてプッシュ
GitHub Actions が自動実行され、Pagefind インデックスが生成・デプロイされます。