Algolia Search 搜索

VitePress 支持使用 Algolia DocSearch 搜索文档站点。

在 Algolia DocSearch 官网填写自己的文档网站的地址和邮箱进行申请

申请通过后，会收到邮件，邮件中包含了 API Key 和 Index Name

需要回复邮件确认申请通过，点击链接到官网注册账号。

在 Algolia 官网 中可以查看到自己的 Application ID 和 API Key。

注意

Write API Key 是私有 API 密钥，用于创建，更新和删除您的索引，不要泄露！

在 VitePress 项目中配置 Algolia DocSearch

在 .vitepress/config.ts 中添加 search 配置项：

config.ts

import { defineConfig } from 'vitepress'
import { algoliaSearch } from './algolia'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'xxx',
        apiKey: 'xxx',
        indexName: 'xxx',

        // 中文转换
        ...algoliaSearch,
      }
    }
  }
})

algolia.ts

import type { DefaultTheme } from 'vitepress'

export const algoliaSearch: Partial<DefaultTheme.AlgoliaSearchOptions> = {
  placeholder: '搜索文档',
  translations: {
    button: {
      buttonText: '搜索文档',
      buttonAriaLabel: '搜索文档',
    },
    modal: {
      searchBox: {
        resetButtonTitle: '清除查询条件',
        resetButtonAriaLabel: '清除查询条件',
        cancelButtonText: '取消',
        cancelButtonAriaLabel: '取消',
      },
      startScreen: {
        recentSearchesTitle: '搜索历史',
        noRecentSearchesText: '没有搜索历史',
        saveRecentSearchButtonTitle: '保存至搜索历史',
        removeRecentSearchButtonTitle: '从搜索历史中移除',
        favoriteSearchesTitle: '收藏',
        removeFavoriteSearchButtonTitle: '从收藏中移除',
      },
      errorScreen: {
        titleText: '无法获取结果',
        helpText: '你可能需要检查你的网络连接',
      },
      footer: {
        selectText: '选择',
        navigateText: '切换',
        closeText: '关闭',
        searchByText: '搜索提供者',
      },
      noResultsScreen: {
        noResultsText: '无法找到相关结果',
        suggestedQueryText: '你可以尝试查询',
        reportMissingResultsText: '你认为该查询应该有结果？',
        reportMissingResultsLinkText: '点击反馈',
      },
    },
  },
}

添加实时更新索引

Github Secrets 中添加私钥

打开 Algolia Crawlers 官网， ALGOLIA_APP_ID 和 Algolia API Key 添加到 Github 项目的 Secrets 中，在 CI 脚本中使用。

• ALGOLIA_APP_ID：取 Algolia 的 Algolia App ID
• ALGOLIA_API_KEY：取 Algolia 的 Algolia API Key

创建 crawlerConfig.json 文件

在项目根目录下新建爬虫 crawlerConfig.json 文件，配置需要爬取的页面。

参考 vitepress 的配置

{
  "index_name": "xxx",
  "start_urls": ["xxx"],
  "rateLimit": 8,
  "maxDepth": 10,
  "selectors": {
    "lvl0": {
      "selector": "",
      "defaultValue": "Documentation"
    },
    "lvl1": ".content h1",
    "lvl2": ".content h2",
    "lvl3": ".content h3",
    "lvl4": ".content h4",
    "lvl5": ".content h5",
    "content": ".content p, .content li",
    "lang": {
      "selector": "/html/@lang",
      "type": "xpath",
      "global": true
    }
  },
  "selectors_exclude": [
    "aside",
    ".page-footer",
    ".next-and-prev-link",
    ".table-of-contents"
  ],
  "custom_settings": {
    "attributesForFaceting": ["lang", "tags"]
  },
  "js_render": true
}

创建 CI 脚本

在项目根目录 .github/workflows 文件夹下创建 algolia.yml 文件

提示

可以添加时间延迟，避免文档更新不及时

- name: Delay before pushing indices to Algolia
  run: sleep 60 && echo "Delay complete, pushing indices now."

name: algolia
on:
  push:
    branches:
      - main
jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get the content of algolia.json as config
        id: algolia_config
        run: echo "config=$(cat crawlerConfig.json | jq -r tostring)" >> $GITHUB_OUTPUT
      - name: Push indices to Algolia
        uses: signcl/docsearch-scraper-action@master
        env:
          APPLICATION_ID: ${{ secrets.ALGOLIA_APP_ID }}
          API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
          CONFIG: ${{ steps.algolia_config.outputs.config }}

出现 Node.js x actions are deprecated 报错？

如果出现 Node.js x actions are deprecated 的提示，可以将 uses: actions/checkout@v4 的版本号升级一下。

出现 Not enough rights to update an object 报错?

错误信息中显示 Not enough rights to update an object ，意味着你使用的 API Key 没有足够的权限来更新 Algolia 的索引对象。