给 VitePress 添加 algolia 搜索

news2024/11/24 17:31:23

大家好，我是 Chocolate。

最近在折腾 VitePress，搭建了一个文档项目：ChoDocs，不过文档还不支持搜索功能，虽然目前内容不多，但待我同步完之后，搜索就很有必要了。

之前看 VitePress 官网发现没有相关介绍文档，不过好在自己对于 algolia 比较熟悉了，于是自己在项目中集成了。

账号与创建应用

需要再 algolia 官网注册一个账号，或者直接选择以 GitHub 身份登录。

登录之后会进入控制台页面，点击右上角头像，会有一个设置选项，之后来到 Applications 这里，去创建一个应用，以我自己的为例，下图已经创建好了「chodocs」。

获取 key

如图下所示，进入 API Keys 页面。

会看到如下界面，一个是可公开的，Search-Only API Key 是待会我们在 VitePress 项目中会使用的，而 Admin API Key 是用于一会爬虫的 key，因为是私有的，所以一会放在 Github Secrets 中。

在文档中填写 key

在上一步我们获取了公开的 key，在这里我们就来配置一下，将上述的 Search-Only API Key 填到 apiKey 字段中，私有的 key 不要填！

修改文件在 docs/.vitepress/config 文件中，具体可参考链接 config.ts。

algolia: {
  appId: 'RDDxxx', // 需要替换
  apiKey: '9302dbxxx', // 需要替换
  indexName: 'chodocs', // 需要替换
  placeholder: '请输入关键词',
  buttonText: '搜索',
}

私钥放在 Github Secrets 中

将上述获取的 Admin API Key 添加到 Github Secrets 中，如下图所示，创建 API_KEY 和 APPLICATION_ID 两个字段，一会在 ci 中会使用到。

创建 crawlerConfig.json

在项目的根目录下创建 crawlerConfig.json 文件，内容如下，注意前两个字段需要进行替换。这是告诉 algolia 需要爬取的配置。

{
  "index_name": "chodocs", // 填写自己的索引名称
  "start_urls": ["https://chodocs.cn/"], // 填写自己的网站地址
  "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"
  },
  "selectors_exclude": [
    "aside",
    ".page-footer",
    ".next-and-prev-link",
    ".table-of-contents"
  ],
  "js_render": true
}

编写 CI 脚本

在项目根目录.github/workflows 文件夹下，创建 algolia.yml 文件（名称可更改，自定义），粘贴如下内容：

name: algolia
on:
  push:
    branches:
      - main
jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - 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.APPLICATION_ID }}
          API_KEY: ${{ secrets.API_KEY }}
          CONFIG: ${{ steps.algolia_config.outputs.config }}