跳到主要内容

搜索

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

信息

🥇 道格龙（Docusaurus）为 Algolia DocSearch 提供一流的支持。

👥 其他选项由社区维护：请向它们各自的代码仓库报告 bug。

🥇 使用 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 时的安装步骤
  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 上启用 insights 功能（默认为 `false`）
      insights: false,

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

在 道格龙（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 文档的英文结果（+ 其他未版本化的页面）
  • 在 /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 变量来设计 DocSearch 的样式，方法是编辑 /src/css/custom.css 文件。

/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 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 用户界面上，你的索引应允许在 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 并从那里创建你自己的搜索组件。