Copy
View as MarkdownOpen in ChatGPTOpen in ClaudeReport an issueShare on XShare on LinkedInShare on Facebook

検索

ガイド検索
このページの内容

検索

BxSites はデフォルトで1つの検索プロバイダーを同梱しており、bxsites.yaml の searchProvider で他のプロバイダーに 切り替えることもできます - どのプロバイダーが有効であっても、search: true/false がマスターのオン/オフスイッチであり続けます。

Local（デフォルト）

BxSites の検索は完全に静的でクライアントサイドです。mkdocs がデフォルトで使用するのと同じアプローチです: build 時に一度作成されるインデックスと、 訪問者のブラウザで実際の検索を行う lunr.js の組み合わせです。 サーバー、データベース、外部検索サービスは一切不要です。

仕組み

  1. build 時に、SearchIndexer がすべての非隠しページを巡回して site/search-index.json を書き出します: 各ページの title、url、 フロントマターの tags、ページ上のすべての見出しのテキスト、 本文の切り詰めたプレーンテキストのコピー（HTML タグを除去）を 1 エントリとして格納します。
  2. 各テーマの search.bxm パーシャルが検索ボックスをレンダリングします。 layout.bxm は bxsites.yaml の search が true で、searchProvider.provider が "local"（デフォルト）の場合のみこれ（と lunr.js + 共有 search.js スクリプト）を含めます（別のプロバイダーでは何が変わるかについては、 下記の その他の検索プロバイダー を参照してください）。
  3. ブラウザでは、共有の assets/search.js ウィジェットが search-index.json を 一度取得し、lunr インデックスをビルドして（title を最高優先度として、 フロントマターの tags、headings、本文テキストの順）、キーストロークごとに 再検索します。クエリごとのネットワークラウンドトリップは発生しません。

キーボードショートカット

  • / は、他のフィールドに入力中でない限り、ページのどこからでも検索ボックスに フォーカスします - mkdocs-material と同じ慣習です。検索ボックスにはプラットフォームを判定した小さな Ctrl K/⌘K のヒントが表示されるため、下記のショートカットに気付けるように なっています。
  • Cmd/Ctrl+K は代わりに、独立したコマンドパレット風のオーバーレイを開きます - 背景の上に中央揃えで表示されるモーダルで、完全に JS だけで構築されており （テーマテンプレートの変更は不要）、すべての組み込みテーマで共有されます。 上下矢印キーで結果のハイライトを移動し、Enter でハイライトされている項目に 移動し、Escape（または背景のクリック）で閉じます - Algolia DocSearch、 Pagefind、VitePress、Docusaurus、GitBook がいずれも共有している、同じ 「クイックファインド」/⌘K の慣習です。
  • Escape は、上のパレットとは独立して、サイドバーのボックス自身の結果 ドロップダウンも閉じ、フォーカスを外します。

このパレットは、search-index.json を再度取得するのではなく、サイドバーの ウィジェット自身がすでにビルド済みの lunr インデックスをそのまま再利用します - これは local（デフォルトのプロバイダー）でのみ利用可能です。algolia は DocSearch 自体から Cmd+K を無料で得られ（keyboardShortcuts のデフォルトは true）、pagefind は、そのライブラリ自体がキーバインドを行わないため、 layout.bxm が Cmd+K を配線して自身の PagefindUI にフォーカスします - どちらもこのモジュール自身のパレットは開きません。

無効化

search: false

{ "search": false }

search-index.json のビルドを完全にスキップし、すべてのレンダリングされたページから 検索ボックス、同梱された（バンドルされた）lunr.js スクリプト、共有 search.js ウィジェットをスキップします。 検索をオフにしたプロジェクトは検索関連のものを一切送信しません。これはマスタースイッチです - どの searchProvider が設定されていても適用されます。

インデックスのみ再ビルド

bxSites search-index

search-index.json を更新するだけの場合に便利です。build はその手順の一つとして これを自動的に実行するため、通常のビルドの後に別途実行する必要はありません。 ローカルインデックスを使用するプロバイダー（"local"、および bx-sites がそれ以外に 認識しないプロバイダー）でのみ実行されます - searchProvider.provider が "algolia" または "pagefind" の場合は、どちらもこれを一切使用しないため、 何もしません（skipped: true）。

Algolia

searchProvider.provider を "algolia" に設定すると、検索ボックスが Algolia DocSearch に切り替わります - mkdocs-material、VitePress、Starlight、Docusaurus がいずれもサポートしている、 同じクローラーホスト型の検索です:

search: true
searchProvider:
  provider: algolia
  algolia:
    appId: ABC123
    apiKey: a1b2c3d4e5f6...
    indexName: my-docs
    insights: false

{
	"search": true,
	"searchProvider": {
		"provider": "algolia",
		"algolia": {
			"appId": "ABC123",
			"apiKey": "a1b2c3d4e5f6...",
			"indexName": "my-docs",
			"insights": false
		}
	}
}

appId、apiKey、indexName は必須です - apiKey は DocSearch が発行する 検索専用の公開 API キーです（管理キーでは決してありません。すべての レンダリング済みページにそのまま出荷されます）。insights（デフォルトは false）は DocSearch 自身のクリック/コンバージョン分析を有効にします。

algolia が有効な場合:

  • search-index.json はビルドされず、共有の lunr.js/search.js ウィジェットも 出荷されません - Algolia は、BxSites がビルド時に書き出す何かからではなく、 DocSearch のクローラー や自身の Algolia Crawler 設定によって投入された、自身がホストするインデックスから結果を提供します。 サイトを DocSearch に個別に登録する（または自身でクローラーを実行する）必要が 依然としてあります - BxSites はクライアントウィジェットを配線するだけです。
  • 各組み込みテーマは代わりに空の #bxsites-search-algolia コンテナをレンダリングし、 layout.bxm が jsDelivr から @docsearch/css/@docsearch/js を読み込んで それに対して docsearch({...}) を呼び出します - DocSearch がそのコンテナに 独自の検索ボタンとモーダルをレンダリングします。

Pagefind

searchProvider.provider を "pagefind" に設定すると、検索ボックスが Pagefind に切り替わります - こちらも完全に静的/ サーバーレスな検索エンジンですが、Algolia のようにクロールされるのではなく、 ビルド済み の site/ HTML からインデックス化されます:

search: true
searchProvider:
  provider: pagefind
  pagefind: { bin: pagefind, options: [] }

{
	"search": true,
	"searchProvider": {
		"provider": "pagefind",
		"pagefind": { "bin": "pagefind", "options": [] }
	}
}

pagefind の両方のキーは任意です - bin（デフォルト "pagefind"）は実行 ファイルの名前/パスで、単純な名前の場合は PATH を基準に解決されます。 options はそのまま渡される追加の生の CLI フラグの配列です （例: ["--exclude-selectors", ".no-index"]）。

pagefind が有効な場合:

  • pagefind CLI 自体は事前にインストールされ PATH 上にある必要があります - BxSites はこれを呼び出すだけです（BoxLang ネイティブのバインディングはなく、 lastUpdated/gh-deploy が git を呼び出すのと同じ理由です）。代わりに インストールすることはありません。 Pagefind のインストールドキュメント を参照してください。lastUpdated とは異なり、バイナリが見つからない/失敗した 場合は、黙って動作を落とすのではなく build を派手に失敗させます （BxSites.PagefindFailed）- 設定された検索プロバイダーが機能しないサイトを 出荷することは、ビルドが失敗するより悪いことだからです。
  • すべてのドキュメントツリー（メイン + バージョン + ロケール）が書き出され、 sitemap.xml/llms.txt が生成された直後に、BxSites は ビルド済みの site/ 全体に対して pagefind --site <siteDir> [...options] を実行します - そのため、マルチバージョン/マルチロケールサイトでも、bx-sites 自身のツリー ごとの search-index.json とは異なり、すべてが一度のパスでインデックス されます。Pagefind は自身のバンドルを site/pagefind/ に直接書き出します - 自己ホスト型で、CDN は関与しません。
  • search-index.json はビルドされず、共有の lunr.js/search.js ウィジェットも 出荷されません（algolia と同様）- 同じ理由で bxSites search-index も 何もしません（上記参照）。
  • 各組み込みテーマは空の #bxsites-search-pagefind コンテナをレンダリングし、 layout.bxm が site/pagefind/pagefind-ui.{css,js} を読み込んで それに対して new PagefindUI({...}) を呼び出します - Pagefind がそのコンテナに 独自のインライン検索ボックスと結果をレンダリングします。

その他の検索プロバイダー

searchProvider.provider は "local"/"algolia"/"pagefind" に限定されません - それ以外の値も bxsites.yaml にそのまま受け入れられます（BxSites 自身の設定 検証は上記の3つのプロバイダーのみをチェックします）。これにはプラグインフックは ありません - 組み込みテーマは、認識されないプロバイダー名に対して単に何も レンダリングしません。4つ目の検索サービス（Meilisearch、Typesense など）を 配線するのは、プロジェクトレベルの テーマオーバーライドです: 組み込みテーマの 1つをプロジェクト自身の theme/ フォルダにコピーし、siteConfig.searchProvider を読み取っていつレンダリングするか判断しながら、layout.bxm/search.bxm に 自分のプロバイダーのマークアップ/スクリプトを追加します - search.bxm の マウントポイント用の searchProviderName eq "..." 分岐、その CSS/JS 用の layout.bxm 内の対応する分岐、そして（Algolia のようにクローラーホスト型 でない場合は）build 後に site/ に対して必要となるインデックス処理ステップを 用意します - これは、このモジュール自身の layout.bxm/BuildPipeline.bx が algolia/pagefind に対してすでに使っているのと同じ形です。

このページを編集 Markdownをダウンロード 最終更新 Aug 28, 2026, 3:16:38 AM