Skip to main content

Algolia DocSearch 配置指南

简介​

Algolia DocSearch 是一个强大的文档搜索服务，可以为技术文档网站提供高质量的搜索体验。本指南将帮助你为 Docusaurus 网站配置 Algolia 搜索功能。

步骤 1: 注册 Algolia 账号​

  1. 访问 Algolia 官网 并注册一个账号
  2. 登录后，创建一个新的应用程序（Application）
  3. 记下你的应用程序 ID（Application ID）

步骤 2: 申请 DocSearch 爬虫或设置自己的爬虫​

选项 A: 申请官方 DocSearch 爬虫（推荐）​

  1. 访问 DocSearch 申请页面
  2. 填写表单，提供你的网站 URL 和其他必要信息
  3. 提交申请后，Algolia 团队会审核你的申请
  4. 如果申请被接受，你将收到一封包含配置信息的电子邮件

选项 B: 设置自己的爬虫​

如果你想自己管理爬虫，可以按照以下步骤操作：

  1. 安装 DocSearch 爬虫：

    npm install @docsearch/scraper

  2. 创建配置文件 docsearch.config.json：

    {
      "index_name": "你的索引名称",
      "start_urls": ["https://你的网站域名/"],
      "sitemap_urls": ["https://你的网站域名/sitemap.xml"],
      "sitemap_alternate_links": true,
      "stop_urls": [],
      "selectors": {
        "lvl0": {
          "selector": ".menu__link--sublist.menu__link--active",
          "global": true,
          "default_value": "Documentation"
        },
        "lvl1": "article h1",
        "lvl2": "article h2",
        "lvl3": "article h3",
        "lvl4": "article h4",
        "lvl5": "article h5, article td:first-child",
        "text": "article p, article li, article td:last-child"
      },
      "strip_chars": " .,;:#",
      "custom_settings": {
        "separatorsToIndex": "_",
        "attributesForFaceting": ["language", "version", "type", "docusaurus_tag"],
        "attributesToRetrieve": ["hierarchy", "content", "anchor", "url", "url_without_anchor", "type"]
      }
    }

  3. 在 Algolia 控制面板中创建 API 密钥：

    • 导航到 API Keys 页面
    • 创建一个新的 API 密钥，具有以下权限：
      • search
      • addObject
      • deleteObject
      • deleteIndex
      • settings
      • editSettings

  4. 运行爬虫：

    docker run -it --env-file=.env -e "CONFIG=$(cat docsearch.config.json | jq -r tostring)" algolia/docsearch-scraper

    其中 .env 文件包含：

    APPLICATION_ID=你的应用ID
    API_KEY=你的管理API密钥

步骤 3: 配置 Docusaurus​

  1. 安装 Algolia 搜索主题：

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

  2. 在 docusaurus.config.ts 中配置 Algolia：

    // docusaurus.config.ts
    export default {
      // ...
      themeConfig: {
        // ...
        algolia: {
          appId: '你的应用ID',           // 你的 Algolia 应用 ID
          apiKey: '你的搜索API密钥',      // 你的搜索 API 密钥（非管理 API 密钥）
          indexName: '你的索引名称',      // 你的索引名称
          contextualSearch: true,        // 启用上下文搜索
          // 可选配置
          searchParameters: {},          // 附加搜索参数
          searchPagePath: 'search',      // 搜索页面路径
        },
        // 注意：启用 Algolia 后，应注释或删除本地搜索配置
        // search: {
        //   provider: require.resolve('@easyops-cn/docusaurus-search-local'),
        //   // ...
        // },
      },
    };

  3. 重启开发服务器：

    npm run start

步骤 4: 验证搜索功能​

  1. 访问你的网站
  2. 点击导航栏中的搜索图标
  3. 输入一些关键词进行搜索
  4. 验证搜索结果是否正确显示

常见问题​

搜索结果为空​

  • 确保爬虫已成功运行并索引了你的网站
  • 检查 Algolia 控制面板中的索引是否包含数据
  • 验证 apiKey 是否为搜索 API 密钥（非管理 API 密钥）

依赖冲突​

如果安装 @docusaurus/theme-search-algolia 时出现依赖冲突，可以尝试：

# 使用 --legacy-peer-deps 选项
npm install --save @docusaurus/theme-search-algolia --legacy-peer-deps

# 或使用 --force 选项
npm install --save @docusaurus/theme-search-algolia --force

本地搜索与 Algolia 搜索共存​

不建议同时启用两种搜索方式，应该选择其中一种：

  • 如果你希望使用 Algolia，请注释或删除本地搜索配置
  • 如果你希望使用本地搜索，请注释或删除 Algolia 配置

资源链接​