版本：3.8.1

搜索

有几种选项可以将搜索功能添加到你的网站

🥇 Algolia DocSearch (官方)
👥 Typesense DocSearch
👥 本地搜索
👥 自定义 SearchBar 组件

信息

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

👥 其他选项由社区维护：请向其各自的代码库报告错误。

🥇 使用 Algolia DocSearch

Docusaurus 官方支持 Algolia DocSearch。

该服务对任何开发者文档或技术博客都是免费的：只需确保阅读申请资格清单并申请加入 DocSearch 项目。

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

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

注意

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

来自旧版 DocSearch？

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

索引配置

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

使用推荐的爬虫配置

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

更新爬虫配置时

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

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

连接 Algolia

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

不使用 @docusaurus/preset-classic 时的安装步骤

安装包

npm
Yarn
pnpm
Bun

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

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

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

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

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

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

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

在 /en/docs/v1/myDoc 上，搜索结果将只包含 v1 文档的英文结果（+ 其他未版本化页面）
在 /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 配备了一个精心调整的主题，专为可访问性设计，确保颜色和对比度符合标准。

不过，你可以通过编辑 /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
Bun

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

yarn swizzle @docusaurus/theme-search-algolia SearchBar

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

bun 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 中 swizzle SearchBar 组件

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

bun run swizzle @docusaurus/theme-classic SearchBar

这将在你的项目文件夹中创建一个 src/theme/SearchBar 文件。重启你的开发服务器并编辑该组件，你会发现 Docusaurus 现在使用了你自己的 SearchBar 组件。

注意：你也可以从 Algolia SearchBar swizzle 并从那里创建你自己的搜索组件。

🥇 使用 Algolia DocSearch​

索引配置​

连接 Algolia​

上下文搜索​

样式化你的 Algolia 搜索​

自定义 Algolia 搜索行为​

编辑 Algolia 搜索组件​

故障排除​

无搜索结果​

支持​

👥 使用 Typesense DocSearch​

👥 使用本地搜索​

👥 使用自定义搜索​