跳到主要内容

搜索

你可以使用以下几种选项为你的网站添加搜索功能：

信息

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

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

🥇 使用 Algolia DocSearch​

Docusaurus 对 Algolia DocSearch 有官方支持。

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

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

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

备注

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

从旧的 docsearch 迁移？

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

索引配置​

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

使用推荐的爬虫配置

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

更新爬虫配置时

爬虫配置包含 initialIndexSettings，仅在 Algolia 索引不存在时使用。

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

连接 Algolia​

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

未使用 @docusaurus/preset-classic 时的安装步骤
  1. 安装包：
npm install --save @docusaurus/theme-search-algolia
  1. 在 docusaurus.config.js 中注册主题：
docusaurus.config.js
export default {
  title: '我的站点',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

然后，在你的 themeConfig 中添加 algolia 字段。申请 DocSearch 以获取你的 Algolia 索引和 API 密钥。

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 中项目 URL 的部分。当使用相同的搜索索引为具有不同 baseUrl 的多个部署提供服务时很有用。你可以在 `from` 参数中使用正则表达式或字符串。例如：localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // 或作为正则表达式：/\/docs\//
        to: '/',
      },

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

      // 可选：默认启用的搜索页面路径（`false` 禁用它）
      searchPagePath: 'search',

      // 可选：是否在 Docsearch 上启用洞察功能（默认为 `false`）
      insights: false,

      //... 其他 Algolia 参数
    },
  },
};
信息

searchParameters 选项在 Docusaurus v1 中曾被命名为 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 文档的英语结果（+ 其他未版本化的页面）
  • 在 /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 分面文档。

上下文搜索不起作用？

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

默认情况下，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);
}

自定义 Algolia 搜索行为​

Algolia DocSearch 支持一个 选项列表，你可以在 docusaurus.config.js 文件的 algolia 字段中传递这些选项。

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    algolia: {
      apiKey: '你的 API 密钥',
      indexName: '你的索引名称',
      // 其他选项...
    },
  },
};

编辑 Algolia 搜索组件​

如果你想编辑 Algolia 搜索 React 组件，请使用 swizzle 命令来处理 @docusaurus/theme-search-algolia 中的 SearchBar 组件：

npm 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 索引显示适当的分面字段

另外，如果你使用 {contextualSearch: false}（我们不特别推荐）禁用上下文搜索，Docusaurus 将不使用分面查询，你应该开始看到结果。

使用推荐的配置

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

你可以通过以下步骤修复索引配置问题：

  1. 使用推荐的爬虫配置
  2. 通过 UI 删除你的索引
  3. 通过 UI 触发新的爬取
  4. 检查你的索引是否使用适当的分面字段重新创建：docusaurus_tag、language、lang、version、type
  5. 查看你现在是否获得搜索结果，即使启用了上下文搜索

支持​

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

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

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

👥 使用 Typesense DocSearch​

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

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

与 Algolia DocSearch 类似，它有两个组件：

阅读如何运行 typesense-docsearch-scraper和如何在你的 Docusaurus 站点中安装搜索栏的分步指南。

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

你可以在这里找到社区支持的本地搜索插件列表。

要使用你自己的搜索，请使用 swizzle 命令处理 @docusaurus/theme-classic 中的 SearchBar 组件

npm run swizzle @docusaurus/theme-classic SearchBar

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

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