サイト検索

zudo-docでの検索の仕組みと設定方法。

検索の仕組み

zudo-doc の組み込み検索ウィジェットは、全文サイト検索にクライアントサイドの単語一致スコアラーを使用します。コンテンツファイル（タイトル、説明、本文）から検索インデックスが生成され、単一のJSONファイルとして配信されます。ブラウザがこのインデックスを読み込み、すべての検索をクライアントサイドで実行します — サーバーや外部サービスは不要です。

各ページの本文は、searchMaxBodyLength 設定で指定した文字数までインデックスされます — デフォルトは3,000文字です。これにより、ページの冒頭だけでなく、長いページの奥深くにあるテキストにもクエリがマッチできるようになります。この設定が制御するのはインデックスの深さだけで、結果に表示される内容には影響しません。マッチ箇所は常に、その位置を中心とした約200文字のコンパクトなスニペットとして表示され、description が設定されていればそちらが本文の代わりに使われます。上限を上げると、その分だけsearch-index.jsonも大きくなります。各ページのインデックス済み抜粋がまるごとブラウザに送られるためです — 旧デフォルトの300文字から3,000に上げると、このショーケースではインデックスサイズがおよそ3.4倍（約410 KBから約1.4 MB）になりました。

エージェント向けの取得は別機能

任意のエージェント向けエクスポートは、searchMaxBodyLengthを超える部分も含む別の全文コーパスを生成します。MCPサーバーはドキュメントクライアント向けに読み取り専用のsearchとfetchツールを提供します。どちらを有効にしても、ブラウザーのウィジェットやSearch Workerの順位付け・インデックスの契約は変わりません。

検索の使い方

検索ダイアログを開くには：

• キーボードショートカット：Ctrl+K（Windows/Linux）またはCmd+K（macOS）

• 検索ボタン：ヘッダーの検索アイコンをクリック

クエリを入力すると結果が即座に表示されます。結果をクリックするとそのページに移動します。

すべての環境で動作

検索はすべての環境で動作します：

• 開発モード（pnpm dev）：検索インデックスはzfbのdevMiddleware経由でオンザフライで生成

• 本番ビルド（pnpm build）：インデックスは静的サイトとともにsearch-index.jsonに出力

• Tauri（オフラインリーダー）：バンドルされたdist/から同じインデックスファイルを読み込み — 特別な処理は不要

ページを検索から除外する

フロントマターにsearch_exclude: true、draft: true、またはunlisted: trueが設定されたページは、検索インデックスから自動的に除外されます。

ページを明示的に除外するには、フロントマターにsearch_exclude: trueを追加します：

---
title: My Internal Page
search_exclude: true
---

検索ウィジェットの置き換え

ヘッダーの検索ウィジェットを置き換えるには、ホストクロームバインディングの SearchWidget スロットを使います。クロームが渡すロケール対応の props は次の7つだけです。

SearchWidget: (props: {
  placeholderText: string;
  shortcutHint: string;
  resultCountTemplate: string;
  searchLabel: string;
  searchUnavailableText: string;
  loadingIndexText: string;
  noResultsText: string;
}) => unknown;

クロームはサイトの base パスを内部で束縛します。ホスト側のウィジェットには base は渡されないため、置き換えコンポーネントでそれを要求しないでください。

検索機能

組み込みウィジェットは以下を提供します：

• 単語一致：クエリ語をタイトル、説明、本文から一致させる

• フィールドスコアリング：タイトルの一致は3点、説明は2点、本文は1点を加算

• 複数語：一致した語とフィールドをまたいでスコアを加算

• 即時結果：フルインデックスが一度読み込まれ、メモリ内でクエリを実行

サーバーサイド検索（Search Worker）

大規模なドキュメントベースやプログラムによるAPIアクセスのために、zudo-docはオプションのSearch Workerを提供しています。これはMiniSearchをサーバーサイドで実行するCloudflare Workerです。

Search Workerを使うべき場合

組み込みのクライアントサイド検索は小〜中規模のドキュメントサイトで十分に動作します。Search Workerは以下の場合に便利です：

• 大きなインデックスサイズ -- フルのsearch-index.jsonがブラウザへのダウンロードには大きすぎる場合

• APIコンシューマー -- ボット、CLIツール、インテグレーションがブラウザなしで検索にアクセスする必要がある場合

• サーバーサイド処理 -- 検索インデックスをクライアントから離したい場合

仕組み

Search Workerはデプロイ済みのサイトから同じsearch-index.jsonを取得し、5分のTTLでキャッシュします。MiniSearch のプレフィックス、ファジー、フィールドブースト設定を使用します。その一致動作は、組み込みウィジェットの単語一致スコアラーとは独立しています。

比較

セットアップ手順、APIドキュメント、デプロイの詳細については、Search Worker APIリファレンスを参照してください。