版本：Canary 🚧

搜索

有几种为你的网站添加搜索功能的方案：

🥇 Algolia DocSearch（官方支持）
👥 Typesense DocSearch
👥 本地搜索
👥 你自己的 SearchBar 组件

信息

🥇 Docusaurus 提供对 Algolia DocSearch 的官方支持。

👥 其他选项是社区维护的：请把 bug 报告给他们各自的仓库。

🥇 使用 Algolia DocSearch

Docusaurus 提供对 Algolia DocSearch 的官方支持。

此服务对开源项目是免费的：你只需要阅读检查清单，然后向 DocSearch 项目申请即可。

Docsearch 每周一次爬取你的网站（可以在网页界面上配置具体时间），并将所有内容汇总到一个 Algolia 索引中。随后，你的前端会调用 Algolia API 来直接查询这些内容。

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

备注

Docusaurus 预设会默认生成一份 sitemap.xml 供 Algolia 爬虫使用。

从旧 DocSearch 迁移来的？

要了解更多关于从旧 DocSearch 架构迁移到新架构的内容，你可以读读我们的博客文章或者 DocSearch 迁移文档。

配置索引

在你的申请被批准并部署完毕后，你会收到一封包含所有详细信息的电子邮件，告诉你如何将 DocSearch 添加到你的项目。可以通过网页界面来编辑和管理你的网站爬取。部署完毕后，索引就立即可用了，所以一般不需要手动配置。

提示

我们强烈建议让你的配置接近于 Docusaurus v3 网站的配置。

连接到 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 字段。要取得你的 Algolia 索引名和 API 密钥，请**向 DocSearch 申请**。

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // Algolia 提供的应用 ID
      appId: 'YOUR_APP_ID',

      //  公开 API 密钥：提交它没有危险
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // 可选：见下文
      contextualSearch: true,

      // 可选：声明哪些域名需要用 window.location 型的导航而不是 history.push。 适用于 Algolia 配置会爬取多个文档站点，而我们想要用 window.location.href 在它们之间跳转时。
      externalUrlRegex: 'external\\.com|domain\\.com',

      // 可选: 替换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: '/',
      },

      // 可选: Algolia 搜索参数
      searchParameters: {},

      // 可选: 搜索页面的路径，默认启用(可用`false`禁用)
      searchPagePath: 'search',

      //... 其它 Algolia 搜索参数
    },
  },
};

信息

searchParameters 选项即 Docusaurus v1 中的 algoliaOptions。

请参阅 DocSearch 官方文档了解可取的值。

注意

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

如果在任何重大更改之后，搜索无法正常工作，请用 Algolia 控制面板触发一次新爬取。

上下文搜索

上下文搜索默认启用。

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

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

假设你有两个文档版本（v1 和 v2）以及两种语言（en 和 zh-Hans）。

浏览 v2 的文档时，返回 v1 文档的搜索结果会很奇怪。有时侯 v1 和 v2 的文档非常相似，导致同一个查询产生重复的搜索结果（每个版本一个结果）。

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

上下文搜索功能解决了这个问题。它能够理解你正在浏览某个文档版本及语言，并动态创建搜索过滤器。

在 /en/docs/v1/myDoc 上，搜索结果将只包含英文 v1 文档的结果（以及其他未分版本的页面）
在 /zh-Hans/docs/v2/myDoc 上，搜索结果将只包含** 中文** v2 文档的结果（以及其他未分版本的页面）

信息

使用 contextualSearch: true（默认开启）时，上下文约束面过滤器 (contextual facet filters) 会和 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);
  /* 弹窗 */
  --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 支持一系列选项。你可以通过 docusaurus.config.js 的 algolia 字段传递它们。

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

编辑 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

支持

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

你可以通过 email 或 Discord 联系他们。

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

👥 使用 Typesense DocSearch

Typesense DocSearch 类似于 Algolia DocSearch，只不过你的网站会被 Typesense 搜索集群索引。

Typesense 是一个开源的即时搜索引擎。你可以：

在你的服务器上部署自己的服务，或者
使用托管的 Typesense 云服务。

与 Algolia DocSearch 类似，Typesense 分为两个部分：

typesense-docsearch-scraper：爬取你的网站，并在你的 Typesense 集群中建立数据索引。
docusaurus-theme-search-typesense：一个搜索栏界面组件，需要添加到你的网站。

关于如何运行 typesense-docsearch-scraper，这里有一个分步教学的指南。这里是如何在你的 Docusaurus 网站上安装搜索栏的教程。

👥 使用本地搜索

对于搜索索引比较小的网站，你可以使用本地搜索插件。索引会在用户访问你的网站时下载到浏览器中。

这里列出了一些社区维护的本地搜索插件。

👥 使用你自己的搜索

要使用你自己的搜索，请 swizzle @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/themes/SearchBar 文件。重启你的开发服务器，编辑组件，你会看到 Docusaurus 开始使用你自己的 SearchBar 组件了。

搜索

🥇 使用 Algolia DocSearch​

配置索引​

连接到 Algolia​

上下文搜索​

设计你的 Algolia 搜索框​

自定义 Algolia 搜索行为​

编辑 Algolia 搜索组件​

支持​

👥 使用 Typesense DocSearch​

👥 使用本地搜索​

👥 使用你自己的搜索​