Version: 3.7.0

搜索

有几种选项可以用来为您的网站添加搜索功能：

🥇 Algolia DocSearch (官方)
👥 Typesense 文档搜索
👥 本地搜索
👥 您自己的 SearchBar 组件

info

🥇 Docusaurus 为 Algolia DocSearch 提供了一流的支持。

👥 其他选项由社区维护：请将错误报告提交到各自的仓库。

🥇 使用 Algolia DocSearch

Docusaurus 对 Algolia DocSearch 有官方支持。

该服务对任何开发者文档或技术博客都是免费的：只需确保阅读检查清单并申请DocSearch计划。

DocSearch 每周爬取您的网站一次（时间表可通过网页界面配置），并将所有内容聚合到 Algolia 索引中。然后使用 Algolia API 直接从您的前端查询此内容。

如果您的网站不符合免费托管版DocSearch的资格，或者如果您的网站位于防火墙后面且不公开，那么您可以运行自己的 DocSearch爬虫。

note

默认情况下，Docusaurus预设会生成一个sitemap.xml，Algolia爬虫可以使用它。

From the old docsearch?

您可以在我们的博客文章或DocSearch迁移文档中了解更多关于从旧版DocSearch基础设施迁移的信息。

索引配置

在您的应用程序被批准并部署后，您将收到一封包含所有详细信息的电子邮件，以便您将DocSearch添加到您的项目中。编辑和管理您的爬虫可以通过网页界面完成。部署后索引立即可用，因此通常不需要手动配置。

Use the recommended crawler config

强烈建议使用我们的官方Docusaurus v3 爬虫配置。如果您选择不同的爬虫配置，我们将无法为您提供支持。

When updating your crawler config

爬虫配置包含一个initialIndexSettings，它仅在您的Algolia索引尚不存在时用于初始化。

如果您更新了initialIndexSettings爬虫设置，可以通过界面手动更新索引，但Algolia团队建议删除您的索引，然后重新启动爬虫以完全使用新设置重新初始化。

连接Algolia

Docusaurus 自带的 @docusaurus/preset-classic 支持 Algolia DocSearch 集成。如果你使用经典预设，则无需额外安装。

Installation steps when not using @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字段。申请DocSearch以获取您的Algolia索引和API密钥。

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
    },
  },
};

info

searchParameters 选项在 Docusaurus v1 中曾被称为 algoliaOptions。

请参考其官方 DocSearch 文档以获取可能的值。

warning

在Algolia抓取您的网站之前，搜索功能将无法可靠工作。

如果在任何重大更改后搜索不起作用，请使用Algolia仪表板触发新的抓取。

上下文搜索

上下文搜索默认启用。

它确保搜索结果与当前语言和版本相关。

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

假设你有2个文档版本（v1 和 v2）和2种语言（en 和 fr）。

在浏览v2文档时，返回v1文档的搜索结果会显得很奇怪。有时v1和v2文档非常相似，你可能会得到相同查询的重复搜索结果（每个版本一个结果）。

同样地，当浏览法语网站时，返回英文文档的搜索结果会显得很奇怪。

为了解决这个问题，上下文搜索功能会理解您正在浏览特定的文档版本和语言，并会动态创建搜索查询过滤器。

在 /en/docs/v1/myDoc 上，搜索结果将仅包括 v1 文档的英文结果（+ 其他未版本化的页面）
在 /fr/docs/v2/myDoc 上，搜索结果将仅包括 v2 文档的法语结果（+ 其他未版本化的页面）

info

当使用 contextualSearch: true（默认）时，上下文分面过滤器将与 algolia.searchParameters.facetFilters 提供的过滤器合并。

对于特定需求，您可以禁用 contextualSearch 并定义自己的 facetFilters：

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

请参考相关的 Algolia 分面文档。

Contextual search doesn't work?

如果您仅在禁用上下文搜索时获得搜索结果，这很可能是由于索引配置问题。

为您的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中swizzle 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时最常见的问题。

无搜索结果

看不到搜索结果通常与索引配置问题有关。

How to check if I have a config problem?

Docusaurus 使用 Algolia faceting 来实现其 Contextual Search 功能，以创建动态查询，例如：

[
  "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 上创建 facet 查询，如下图所示：

Algolia index showing appropriate faceting fields

或者，如果您使用 {contextualSearch: false} 禁用 Contextual Search（我们不特别推荐这样做），Docusaurus 将不会使用 facet 查询，您应该会开始看到结果。

Use the recommended configuration

我们推荐特定的爬虫配置是有充分理由的。如果您选择使用不同的配置，我们将无法为您提供支持。

你可以按照以下步骤修复索引配置问题：

使用推荐的爬虫配置
通过用户界面删除您的索引
通过用户界面触发新的爬取
检查您的索引是否已使用适当的分面字段重新创建：docusaurus_tag, language, lang, version, type
查看您现在是否获得了搜索结果，即使启用了上下文搜索

支持

Algolia DocSearch 团队可以帮助您解决网站上的搜索问题。

您可以通过他们的支持页面或Discord联系Algolia。

Docusaurus 在 Discord 上也有一个 #algolia 频道。

👥 使用 Typesense DocSearch

Typesense DocSearch 的工作方式与 Algolia DocSearch 类似，不同之处在于您的网站会被索引到 Typesense 搜索集群中。

Typesense 是一个开源即时搜索引擎，你可以选择：

自托管在您自己的服务器上或
使用托管的Typesense Cloud服务。

类似于Algolia DocSearch，有两个组件：

typesense-docsearch-scraper - 抓取您的网站并将数据索引到您的Typesense集群中。
docusaurus-theme-search-typesense - 一个搜索栏UI组件，可以添加到您的网站。

阅读如何在此处运行typesense-docsearch-scraper以及如何在您的Docusaurus站点中安装搜索栏的逐步指南。

👥 使用本地搜索

您可以使用本地搜索插件，适用于搜索索引较小且可以在用户访问您的网站时下载到他们浏览器中的网站。

您会找到一个社区支持的本地搜索插件列表。

👥 使用你自己的搜索

要使用您自己的搜索，请在@docusaurus/theme-classic中混入SearchBar组件

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中提取并从中创建你自己的搜索组件。

🥇 使用 Algolia DocSearch​

索引配置​

连接Algolia​

上下文搜索​

为您的Algolia搜索添加样式​

自定义Algolia搜索行为​

编辑Algolia搜索组件​

故障排除​

无搜索结果​

支持​

👥 使用 Typesense DocSearch​

👥 使用本地搜索​

👥 使用你自己的搜索​

🥇 使用 Algolia DocSearch

索引配置

连接Algolia

上下文搜索

为您的Algolia搜索添加样式

自定义Algolia搜索行为

编辑Algolia搜索组件

故障排除

无搜索结果

支持

👥 使用 Typesense DocSearch

👥 使用本地搜索

👥 使用你自己的搜索