バージョン: 3.5.2

検索

ウェブサイトに検索機能を追加するには、いくつかのオプションがあります。

🥇 Algolia DocSearch (公式)
👥 Typesense DocSearch
👥 ローカル検索
👥 独自の SearchBar コンポーネント

情報

🥇 Docusaurus は Algolia DocSearch を公式にサポートしています。

👥 その他のオプションはコミュニティによってメンテナンスされています。バグはそれぞれのレポジトリに報告してください。

🥇 Algolia DocSearch の使用

Docusaurus は Algolia DocSearch を公式にサポートしています。

このサービスは、開発者向けドキュメントまたは技術ブログであれば無料です。チェックリストを読んで、DocSearch プログラムに申し込んでください。

DocSearch は週に一度ウェブサイトをクロールし（スケジュールは Web インターフェースから設定可能）、すべてのコンテンツを Algolia インデックスに集約します。このコンテンツは、Algolia API を使用してフロントエンドから直接クエリされます。

あなたのウェブサイトが無料のホスト型 DocSearch の対象外である場合、またはあなたのウェブサイトがファイアウォールの内側にあり公開されていない場合は、独自の DocSearch クローラを実行できます。

注記

デフォルトでは、Docusaurus プリセットは Algolia クローラが使用できる sitemap.xml を生成します。

～省略～/span>以前の docsearch から？

以前の DocSearch インフラからの移行については、ブログ記事または DocSearch 移行ドキュメントをご覧ください。

インデックスの設定

アプリケーションが承認され、デプロイされると、プロジェクトに DocSearch を追加するための詳細が記載されたメールが届きます。クロールの編集と管理は、Web インターフェースから行うことができます。インデックスはデプロイ後すぐに利用できるため、通常は手動設定は必要ありません。

～省略～/span>推奨されるクローラ設定を使用する

公式の Docusaurus v3 クローラ設定 を使用することを強くお勧めします。別のクローラ設定を選択した場合、サポートすることはできません。

～省略～/span>クローラ設定を更新する場合

クローラ設定には initialIndexSettings が含まれており、これは Algolia インデックスがまだ存在しない場合にのみ初期化に使用されます。

initialIndexSettings クローラ設定を更新する場合、インターフェースからインデックスを手動で更新できますが、Algolia チームはインデックスを削除してからクロールを再開して、新しい設定で完全に再初期化することを推奨しています。

Algolia の接続

Docusaurus 自身の @docusaurus/preset-classic は Algolia DocSearch 統合をサポートしています。classic プリセットを使用する場合、追加のインストールは必要ありません。

@docusaurus/preset-classic を使用しない場合のインストール手順

パッケージをインストールする

npm
Yarn
pnpm

npm install --save @docusaurus/theme-search-algolia

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

docusaurus.config.js にテーマを登録する

docusaurus.config.js
export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

次に、themeConfig に algolia フィールドを追加します。Algolia インデックスと API キーを取得するには、DocSearch に申し込んでください。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // Optional: see doc section below
      contextualSearch: true,

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
      externalUrlRegex: 'external\\.com|domain\\.com',

      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // Optional: Algolia search parameters
      searchParameters: {},

      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
      insights: false,

      //... other Algolia params
    },
  },
};

情報

searchParameters オプションは、Docusaurus v1 では algoliaOptions という名前でした。

使用可能な値については、公式 DocSearch ドキュメントを参照してください。

～省略～/span>警告

Algolia がサイトをクロールするまで、検索機能は正常に動作しません。

大きな変更後も検索が機能しない場合は、Algolia ダッシュボードを使用して新しいクロールをトリガーしてください。

コンテキスト検索

コンテキスト検索はデフォルトで有効になっています。

検索結果が現在の言語とバージョンに関連していることを保証します。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};

2 つのドキュメントバージョン (v1 と v2) と 2 つの言語 (en と fr) があるとします。

v2 ドキュメントを参照しているときに、v1 ドキュメントの検索結果が返されると奇妙です。 v1 と v2 のドキュメントは非常によく似ていることがあり、同じクエリに対して重複した検索結果 (バージョンごとに 1 つの結果) が表示される可能性があります。

同様に、フランス語サイトを参照しているときに、英語ドキュメントの検索結果が返されると奇妙です。

この問題を解決するために、コンテキスト検索機能は、特定のドキュメントバージョンと言語を参照していることを理解し、検索クエリフィルターを動的に作成します。

/en/docs/v1/myDoc では、検索結果には英語のv1ドキュメントの結果（+その他のバージョン管理されていないページ）のみが含まれます。
/fr/docs/v2/myDoc では、検索結果にはフランス語のv2ドキュメントの結果（+その他のバージョン管理されていないページ）のみが含まれます。

情報

contextualSearch: true (デフォルト) を使用する場合、コンテキストファセットフィルターは algolia.searchParameters.facetFilters で提供されるフィルターとマージされます。

特定のニーズに合わせて、contextualSearch を無効にして、独自の facetFilters を定義できます。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: false,
      searchParameters: {
        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
      },
    },
  },
};

関連する Algolia ファセットドキュメントを参照してください。

～省略～/span>コンテキスト検索が機能しない？

コンテキスト検索が無効になっている場合にのみ検索結果が得られる場合、これはインデックス設定の問題である可能性が非常に高くなります。

Algolia 検索のスタイリング

デフォルトでは、DocSearch にはアクセシビリティを考慮して微調整されたテーマが付属しており、色とコントラストが標準に準拠していることを確認しています。

それでも、/src/css/custom.css ファイルを編集することで、Docusaurus の Infima CSS 変数を再利用して DocSearch のスタイルを設定できます。

/src/css/custom.css
[data-theme='light'] .DocSearch {
  /* --docsearch-primary-color: var(--ifm-color-primary); */
  /* --docsearch-text-color: var(--ifm-font-color-base); */
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(94, 100, 112, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-color-secondary);
  --docsearch-searchbox-focus-background: var(--ifm-color-white);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-white);
  /* Footer */
  --docsearch-footer-background: var(--ifm-color-white);
}

[data-theme='dark'] .DocSearch {
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(47, 55, 69, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-background-color);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-background-color);
  --docsearch-searchbox-focus-background: var(--ifm-color-black);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-emphasis-100);
  /* Footer */
  --docsearch-footer-background: var(--ifm-background-surface-color);
  --docsearch-key-gradient: linear-gradient(
    -26.5deg,
    var(--ifm-color-emphasis-200) 0%,
    var(--ifm-color-emphasis-100) 100%
  );
}

Algolia 検索動作のカスタマイズ

Algolia DocSearch は、docusaurus.config.js ファイルの algolia フィールドに渡すことができるオプションのリストをサポートしています。

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    algolia: {
      apiKey: 'YOUR_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      // Options...
    },
  },
};

Algolia 検索コンポーネントの編集

Algolia 検索 React コンポーネントを編集する場合は、@docusaurus/theme-search-algolia の SearchBar コンポーネントをスウィズルします。

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-search-algolia SearchBar

yarn swizzle @docusaurus/theme-search-algolia SearchBar

pnpm run swizzle @docusaurus/theme-search-algolia SearchBar

トラブルシューティング

Docusaurus ユーザーが Algolia DocSearch を使用するときに直面する最も一般的な問題を以下に示します。

検索結果なし

検索結果が表示されない場合は、通常、インデックス設定の問題が原因です。

設定に問題があるかどうかを確認するにはどうすればよいですか？

Docusaurusは、Algoliaファセットをコンテキスト検索機能に使用し、次のような動的クエリを作成します。

[
  "language:en",
  [
    "docusaurus_tag:default",
    "docusaurus_tag:docs-default-3.2.1",
    "docusaurus_tag:docs-community-current",
    "docusaurus_tag:docs-docs-tests-current"
  ]
]

AlgoliaのUIでは、以下のスクリーンショットに示すように、インデックスで`docusaurus_tag`、`language`、`lang`、`version`、`type`のフィールドに対するファセットクエリを作成できる必要があります。

Algolia index showing appropriate faceting fields

または、`{contextualSearch: false}`を使用してコンテキスト検索を無効にした場合（特に推奨しません）、Docusaurusはファセットクエリを使用せず、検索結果が表示されるはずです。

推奨設定を使用してください

正当な理由により、特定のクローラー設定を推奨しています。異なる設定を使用することを選択した場合、サポートすることはできません。

以下の手順に従って、インデックス設定の問題を修正できます。

推奨されるクローラー設定を使用してください
UIからインデックスを削除します
UIから新しいクロールをトリガーします
インデックスが適切なファセットフィールド（`docusaurus_tag`、`language`、`lang`、`version`、`type`）で再作成されていることを確認します
コンテキスト検索が有効になっている場合でも、検索結果が表示されることを確認します

サポート

Algolia DocSearchチームは、サイトの検索問題の解決を支援できます。

サポートページまたはDiscordからAlgoliaに連絡できます。

Docusaurusには、Discordに`#algolia`チャンネルもあります。

👥 Typesense DocSearchの使用

Typesense DocSearchは、ウェブサイトがTypesense検索クラスターにインデックスされることを除いて、Algolia DocSearchと同様に機能します。

Typesenseは、オープンソースのインスタント検索エンジンであり、次のいずれかの方法で利用できます。

独自のサーバーでセルフホストするか、
マネージドTypesense Cloudサービスを使用します。

Algolia DocSearchと同様に、2つのコンポーネントがあります。

typesense-docsearch-scraper - ウェブサイトをスクレイピングし、データをTypesenseクラスターにインデックスします。
docusaurus-theme-search-typesense - ウェブサイトに追加する検索バーUIコンポーネントです。

typesense-docsearch-scraperを実行する方法とDocusaurusサイトに検索バーをインストールする方法のステップバイステップのチュートリアルをご覧ください。

👥 ローカル検索の使用

検索インデックスが小さく、ユーザーがウェブサイトにアクセスしたときにブラウザにダウンロードできるウェブサイトでは、ローカル検索プラグインを使用できます。

コミュニティでサポートされているローカル検索プラグインのリストはこちらにあります。

👥 独自の検索の使用

独自の検索を使用するには、`@docusaurus/theme-classic`の`SearchBar`コンポーネントをswizzleします。

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

これにより、プロジェクトフォルダーに`src/theme/SearchBar`ファイルが作成されます。開発サーバーを再起動してコンポーネントを編集すると、Docusaurusが独自の`SearchBar`コンポーネントを使用していることがわかります。

注：代わりに、Algolia SearchBarからswizzleして、そこから独自の検索コンポーネントを作成することもできます。

🥇 Algolia DocSearch の使用​

インデックスの設定​

Algolia の接続​

コンテキスト検索​

Algolia 検索のスタイリング​

Algolia 検索動作のカスタマイズ​

Algolia 検索コンポーネントの編集​

トラブルシューティング​

検索結果なし​

サポート​

👥 Typesense DocSearchの使用​

👥 ローカル検索の使用​

👥 独自の検索の使用​