版本：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 预设会生成一个 sitemap.xml，Algolia 爬虫可以使用该文件。

来自旧版 Docsearch？

您可以在我们的博文或 DocSearch 迁移文档中阅读有关从旧版 DocSearch 基础设施迁移的更多信息。

索引配置

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

使用推荐的爬虫配置

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

更新爬虫配置时

爬虫配置包含一个 initialIndexSettings，如果您的 Algolia 索引尚不存在，则仅使用它来初始化索引。

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

连接 Algolia

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

不使用 @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
    },
  },
};

信息

在 Docusaurus v1 中，searchParameters 选项以前称为 algoliaOptions。

有关可能的值，请参阅其官方 DocSearch 文档。

警告

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

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

上下文搜索

上下文搜索**默认启用**。

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

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

假设您有两个文档版本（**v1** 和 **v2**）和两种语言（en 和 fr）。

浏览 v2 文档时，返回 v1 文档的搜索结果将很奇怪。有时 v1 和 v2 文档非常相似，您最终会对相同的查询获得重复的搜索结果（每个版本一个结果）。

同样，在浏览法语网站时，返回英语文档的搜索结果将很奇怪。

为了解决此问题，上下文搜索功能了解您正在浏览特定文档版本和语言，并将动态创建搜索查询筛选器。

在 /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 方面文档。

上下文搜索不起作用？

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

设置 Algolia 搜索样式

默认情况下，DocSearch 附带经过精心调整的主题，该主题专为可访问性而设计，确保颜色和对比度符合标准。

不过，您仍然可以使用 Docusaurus 中的 Infima CSS 变量通过编辑 /src/css/custom.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 组件，请 swizzle @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 的工作原理类似于 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​

👥 使用本地搜索​

👥 使用您自己的搜索​