Skip to main content

検索

ウェブサイトに検索機能を追加するには、いくつかの選択肢が利用できます。

情報

🥇 Docusaurus provides first-class support for Algolia DocSearch.

👥 Other options are maintained by the community: please report bugs to their respective repositories.

🥇 Algolia DocSearchを使用する​

Docusaurus has official support for Algolia DocSearch.

The service is free for any developer documentation or technical blog: just make sure to read the checklist and apply to the DocSearch program.

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

If your website is not eligible for the free, hosted version of DocSearch, or if your website sits behind a firewall and is not public, then you can run your own DocSearch crawler.

メモ

By default, the Docusaurus preset generates a sitemap.xml that the Algolia crawler can use.

From the old docsearch?

You can read more about migration from the legacy DocSearch infra in our blog post or the DocSearch migration docs.

インデックス設定​

あなたの申請が承認され、デプロイされると、プロジェクトにDocSearchを追加するための詳細情報が記載されたメールが届きます。 Editing and managing your crawls can be done via the web interface. インデックスはデプロイ後すぐに利用可能なので、手動での設定は通常必要ありません。

Use the recommended crawler config

It is highly recommended to use our official Docusaurus v3 crawler configuration. 別のクローラー設定を選択した場合、サポートを提供できません。

When updating your crawler config

The crawler configuration contains a initialIndexSettings, which will only be used to initialize your Algolia index if it does not exist yet.

If you update your initialIndexSettings crawler setting, it is possible to update the index manually through the interface, but the Algolia team recommends to delete your index and then restart a crawl to fully reinitialize it with the new settings.

Algoliaの接続​

Docusaurus' own @docusaurus/preset-classic supports Algolia DocSearch integration. classicプリセットを使用する場合、追加のインストールは不要です。

Installation steps when not using @docusaurus/preset-classic
  1. パッケージをインストールする:
npm install --save @docusaurus/theme-search-algolia
  1. Register the theme in docusaurus.config.js:
docusaurus.config.js
export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

Then, add an algolia field in your themeConfig. Apply for DocSearch to get your Algolia index and API key.

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,

      // Optional: whether you want to use the new Ask AI feature (undefined by default)
      askAi: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',

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

The searchParameters option used to be named algoliaOptions in Docusaurus v1.

Refer to its official DocSearch documentation for possible values.

警告

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

If search doesn't work after any significant change, please use the Algolia dashboard to trigger a new crawl.

Contextual search is enabled by default.

It ensures that search results are relevant to the current language and version.

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

Let's consider you have 2 docs versions (v1 and v2) and 2 languages (en and fr).

v2のドキュメントを閲覧しているときに、v1のドキュメントの検索結果が返されるのはおかしいです。 時にはv1とv2のドキュメントが非常に似ていることがあり、同じクエリに対して重複する検索結果（バージョンごとに1つの結果）が表示されることになります。

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

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

  • on /en/docs/v1/myDoc, search results will only include English results for the v1 docs (+ other unversioned pages)
  • on /fr/docs/v2/myDoc, search results will only include French results for the v2 docs (+ other unversioned pages)
情報

When using contextualSearch: true (default), the contextual facet filters will be merged with the ones provided with algolia.searchParameters.facetFilters .

For specific needs, you can disable contextualSearch and define your own facetFilters:

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

Refer to the relevant Algolia faceting documentation.

Contextual search doesn't work?

If you only get search results when Contextual Search is disabled, this is very likely because of an index configuration issue.

Ask AI​

Ask AI is a new feature that allows you to ask questions about your documentation.

Ask AI brings the power of AI to your documentation:

  • Conversational search: Users can ask questions in natural language and get context-aware answers.
  • Completely free: Ask AI is available at no additional cost. You'll pay only for the LLM usage to your provider.
  • BYOLLM (Bring Your Own LLM): You can use your own language model provider, giving you full control over the AI experience.
  • Direct Algolia index integration: The provider/models retrieve relevant context directly from your Algolia index, ensuring accurate and up-to-date answers.
  • Recently asked & conversation history: Easily revisit your recent questions and jump back into previous Ask AI conversations.
  • Seamless integration: Ask AI is available directly from the search modal.

To enable it, add an askAi field in your algolia config:

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      askAi: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',

      // OR with custom parameters
      askAi: {
        assistantId: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',
        indexName: 'YOUR_ALGOLIA_INDEX_NAME',
        apiKey: 'YOUR_ALGOLIA_API_KEY',
        appId: 'YOUR_ALGOLIA_APP_ID',
        suggestedQuestions: true, // Optional: enable suggested questions (default: false)
      },

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

To use Ask AI, you need to have an Algolia index with the Ask AI assistant enabled. Learn more about how to setup Ask AI.

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

Still, you can reuse the Infima CSS variables from Docusaurus to style DocSearch by editing the /src/css/custom.css file.

/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);
  /* モーダル */
  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
  /* 検索ボックス */
  --docsearch-searchbox-background: var(--ifm-color-secondary);
  --docsearch-searchbox-focus-background: var(--ifm-color-white);
  /* ヒット */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-white);
  /* フッタ */
  --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);
  /* モーダル */
  --docsearch-modal-background: var(--ifm-background-color);
  /* 検索ボックス */
  --docsearch-searchbox-background: var(--ifm-background-color);
  --docsearch-searchbox-focus-background: var(--ifm-color-black);
  /* ヒット */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-emphasis-100);
  /* フッタ */
  --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 supports a list of options that you can pass to the algolia field in the docusaurus.config.js file.

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

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

If you prefer to edit the Algolia search React component, swizzle the SearchBar component in @docusaurus/theme-search-algolia:

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

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

Docusaurus ユーザーが Algolia DocSearch を使用する際に遭遇する最もよくある問題を紹介します。

検索結果がない​

Seeing no search results is usually related to an index configuration problem.

How to check if I have a config problem?

Docusaurus uses Algolia faceting for its Contextual Search feature, to create dynamic queries such as:

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

On the Algolia UI, your index should allow to create facet queries on fields docusaurus_tag, language, lang, version, type, as shown in the screenshot below:

Algolia index showing appropriate faceting fields

Alternatively, if you disable Contextual Search with {contextualSearch: false} (which we don't particularly recommend), Docusaurus will not use facet queries, and you should start seeing results.

Use the recommended configuration

We recommend a specific crawler configuration for a good reason. We cannot support you if you choose to use a different configuration.

You can fix index configuration problems by following those steps:

  1. Use the recommend crawler configuration
  2. Delete your index through the UI
  3. Trigger a new crawl through the UI
  4. Check your index is recreated with the appropriate faceting fields: docusaurus_tag, language, lang, version, type
  5. See that you now get search results, even with Contextual Search enabled

サポート​

The Algolia DocSearch team can help you figure out search problems on your site.

You can reach out to Algolia via their support page or on Discord.

Docusaurus also has an #algolia channel on Discord.

👥 Typesense DocSearchを使用する​

Typesense DocSearch works similar to Algolia DocSearch, except that your website is indexed into a Typesense search cluster.

Typesense is an open source instant-search engine that you can either:

Similar to Algolia DocSearch, there are two components:

Read a step-by-step walk-through of how to run typesense-docsearch-scraper here and how to install the Search Bar in your Docusaurus Site here.

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

You'll find a list of community-supported local search plugins listed here.

To use your own search, swizzle the SearchBar component in @docusaurus/theme-classic

npm run swizzle @docusaurus/theme-classic SearchBar

This will create an src/theme/SearchBar file in your project folder. Restart your dev server and edit the component, you will see that Docusaurus uses your own SearchBar component now.

Notes: You can alternatively swizzle from Algolia SearchBar and create your own search component from there.