## 検索の仕組み zudo-doc の組み込み検索ウィジェットは、全文サイト検索にクライアントサイドの単語一致スコアラーを使用します。コンテンツファイル（タイトル、説明、本文）から検索インデックスが生成され、単一のJSONファイルとして配信されます。ブラウザがこのインデックスを読み込み、すべての検索をクライアントサイドで実行します — サーバーや外部サービスは不要です。 各ページの本文は、[`searchMaxBodyLength`](https://zudo-doc.takazudomodular.com/ja/docs/guides/configuration#%E6%A4%9C%E7%B4%A2-searchmaxbodylength) 設定で指定した文字数までインデックスされます — デフォルトは3,000文字です。これにより、ページの冒頭だけでなく、長いページの奥深くにあるテキストにもクエリがマッチできるようになります。この設定が制御するのはインデックスの深さだけで、結果に表示される内容には影響しません。マッチ箇所は常に、その位置を中心とした約200文字のコンパクトなスニペットとして表示され、description が設定されていればそちらが本文の代わりに使われます。上限を上げると、その分だけ`search-index.json`も大きくなります。各ページのインデックス済み抜粋がまるごとブラウザに送られるためです — 旧デフォルトの300文字から3,000に上げると、このショーケースではインデックスサイズがおよそ3.4倍（約410 KBから約1.4 MB）になりました。 [Dynamic content unavailable in text export] オプションの [Search Worker](https://zudo-doc.takazudomodular.com/ja/docs/guides/search#%E3%82%B5%E3%83%BC%E3%83%90%E3%83%BC%E3%82%B5%E3%82%A4%E3%83%89%E6%A4%9C%E7%B4%A2%EF%BC%88search-worker%EF%BC%89) も、同じ `searchMaxBodyLength` で切り詰められた本文をインデックスします。そのため、この設定を変更すると、組み込みウィジェットと Search Worker の両方に影響します。 ## エージェント向けの取得は別機能 任意の[エージェント向けエクスポート](https://zudo-doc.takazudomodular.com/ja/docs/guides/agent-export)は、`searchMaxBodyLength`を超える部分も含む別の全文コーパスを生成します。[MCPサーバー](https://zudo-doc.takazudomodular.com/ja/docs/guides/mcp-server)はドキュメントクライアント向けに読み取り専用の`search`と`fetch`ツールを提供します。どちらを有効にしても、ブラウザーのウィジェットやSearch Workerの順位付け・インデックスの契約は変わりません。 ## 検索の使い方 検索ダイアログを開くには： - **キーボードショートカット**：`Ctrl+K`（Windows/Linux）または`Cmd+K`（macOS） - **検索ボタン**：ヘッダーの検索アイコンをクリック クエリを入力すると結果が即座に表示されます。結果をクリックするとそのページに移動します。 ## すべての環境で動作 検索はすべての環境で動作します： - **開発モード**（`pnpm dev`）：検索インデックスはzfbのdevMiddleware経由でオンザフライで生成 - **本番ビルド**（`pnpm build`）：インデックスは静的サイトとともに`search-index.json`に出力 - **Tauri**（オフラインリーダー）：バンドルされた`dist/`から同じインデックスファイルを読み込み — 特別な処理は不要 [Dynamic content unavailable in text export] 検索をテストするためにビルドする必要はありません。`pnpm dev`ですぐに動作します。 ## ページを検索から除外する フロントマターに`search_exclude: true`、`draft: true`、または`unlisted: true`が設定されたページは、検索インデックスから自動的に除外されます。 ページを明示的に除外するには、フロントマターに`search_exclude: true`を追加します： ```mdx --- title: My Internal Page search_exclude: true --- ``` [Dynamic content unavailable in text export] これは変更履歴、インポートされたコンテンツ（例：CLAUDE.md）、検索結果を煩雑にする内部専用ページなどに便利です。 ## 検索ウィジェットの置き換え ヘッダーの検索ウィジェットを置き換えるには、[ホストクロームバインディング](https://zudo-doc.takazudomodular.com/ja/docs/reference/host-chrome-bindings)の `SearchWidget` スロットを使います。クロームが渡すロケール対応の props は次の7つだけです。 ```ts 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 のプレフィックス、ファジー、フィールドブースト設定を使用します。その一致動作は、組み込みウィジェットの単語一致スコアラーとは独立しています。 ### 比較 | 機能 | クライアントサイド検索（組み込み） | Search Worker | | ------------------------ | ---------------------------------- | -------------------------- | | ランタイム | ブラウザ（インメモリ） | Cloudflare Workers | | セットアップ | 不要（デフォルトで有効） | Cloudflareアカウント + KV | | インデックスダウンロード | フルインデックスをブラウザに送信 | インデックスはサーバーサイドに留まる | | 最適な用途 | 小〜中規模のドキュメント | 大規模なドキュメント、APIコンシューマー | | レイテンシ | 即時（ローカル） | ネットワークラウンドトリップ | セットアップ手順、APIドキュメント、デプロイの詳細については、[Search Worker APIリファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/search-worker)を参照してください。