Skip to main content

搜索插件

使用搜索插件提高网站的使用效率和用户体验。

1. 使用官方提供的 Algolia DocSearch​

Docusaurus 提供了与 Algolia DocSearch 的集成，这是官方推荐的搜索解决方案。

配置步骤：​

  1. 申请 Algolia DocSearch
    到 DocSearch 申请页面 提交申请，并提供站点信息。通过审核后，Algolia 会为你提供 API Key 和索引配置。

  2. 安装依赖
    在 Docusaurus 项目中安装 Algolia 搜索插件：

    npm install @docusaurus/theme-search-algolia

  3. 修改配置
    编辑 docusaurus.config.js，添加 Algolia 配置：

    module.exports = {
      themeConfig: {
        algolia: {
          // 必要的配置项
          appId: 'IL9I8Rp4m8', // Algolia 应用的 ID，用于标识特定的搜索服务实例
          apiKey: '319ee55a5xva1b1db5f81d4ab57f2d5x', // Algolia 的 API 密钥，提供访问权限（应妥善保管）
          indexName: 'zxzsk', // Algolia 索引的名称，用于存储和检索搜索数据

          // 可选配置项
          contextualSearch: true, // 启用上下文搜索，依据当前页面内容调整搜索结果的相关性
          externalUrlRegex: 'external\\.com|domain\\.com', // 正则表达式，匹配允许跳转的外部链接域名
          replaceSearchResultPathname: {
            from: '/docs/', // 定义搜索结果中路径替换的来源路径（字符串或正则表达式）
            to: '/', // 替换为的新路径
          },
          searchParameters: {}, // 自定义 Algolia 搜索参数的对象，用于高级搜索配置
          searchPagePath: 'false', // 指定搜索结果页面路径，设置为 'false' 时禁用单独的搜索结果页面
          insights: false, // 是否启用 Algolia Insights 分析功能，用于用户行为追踪
        },

    };

  4. 编译网站，重新发布

note

用了一段时间了。优点：搜索非常块，不漏内容。缺点：网站更新后不能立刻与搜索插件同步，Algolia每周爬取一次网站内容，更新搜索索引。

2. 使用社区插件或本地搜索解决方案​

如果你不想使用 Algolia，也可以选择本地搜索功能。

docusaurus-search-local 是一个本地搜索插件，适合无需外部服务的场景。

note

Algolia不限制返回的结果数量，这个插件似乎限制最多返回8个搜索结果。以搜索“命令”为例，Algolia返回2000+结果，而这个插件只返回8个结果。

image-20250115085028242

此外，关于配置：起先抄了github的默认配置，许多内容搜索不到。后来添加了一些配置项，就可以正常搜索了。README中提供了许多选项和说明。

image-20250114171953207

我的配置项

docusaurus.config.js
  themes: [
    '@docusaurus/theme-mermaid',
    '@docusaurus/theme-live-codeblock',
    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        hashed: true,   // 是否对搜索结果进行hash
        language: ["en", "zh"], // 搜索语言
        indexDocs: true, // 是否对docs进行索引
        indexBlog: false, // 是否对blog进行索引
        indexPages: false, // 是否对pages进行索引
        docsRouteBasePath: ["/"], // 配置需要搜索的文档路径
        searchResultLimits: 8, // 限制返回数量 别调太大
        highlightSearchTermsOnTargetPage: true, // 在文章中高亮关键词

      }),
    ],
  ],

这个插件还有一些细节需要打磨，返回数量别调太大，否则 UI 会挡住界面。

3. 自定义搜索功能​

如果需要高度定制的搜索体验，可以基于 ElasticSearch、MeiliSearch 或其他搜索引擎自行开发搜索功能，并将其嵌入到 Docusaurus 中。

总结​

  • 对于大多数站点，Algolia DocSearch 是最佳选择。
  • 对于小型站点或无需外部依赖的场景，使用 lunr.js 或 docusaurus-search-local 是不错的选择。
  • 如果你需要灵活性，可以基于自己的需求开发搜索功能。
Last updated on