Jacinda

Appearance

On this page
🎨 作者：Jacinda 📔 阅读量：

给 VitePress 添加 algolia 搜索 ​

趁着工作不忙的时候，再一次折腾起VitePress。 由于最近归档写了很多，就想给这个归档文博添加一个搜索框。方便后面文档越来越多，自己搜索起来也方便查找。

在给 VitePress 添加搜索功能时，也遇到了些许坑，也查找了很多文档，现就对其进行归纳

创建账号与应用 ​

首先，你得有一个 algolia 的账号，由于该网站支持 Github 登录，所以采用 Github 直接授权登录相对快速一些。

登录之后会进入控制台页面，请找到 设置 点击进入。

之后来到 Applications 这里，去创建一个应用

图 1

图 2

填写应用名称

图 3

点击 [Next Step]，进入节点选择，一步步往下即可。

下图是我创建好的应用

图 4

获取 Key ​

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

图 5

会看到如下界面

  • Search-Only API Key 可公开的，是我们在 VitePress 项目中会使用的

  • Admin API Key 是用于一会爬虫的 key，因为是私有的，所以会放在 Github Secrets 中。

图 6

在文档中填写 key ​

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

修改文件在 docs/.vitepress/config 文件中

javascript
themeConfig: {
    algolia: {
        appId: '', // 填入上面刚创建好的 Application Id
        apiKey: '', // 填入公开Key
        indexName: 'jacinda', // 需要替换 替换成自己创建的索引
        placeholder: '请输入关键词',
        translations: {
            button: {
                buttonText: '搜索文档',
            },
        },
    }
},

创建索引 ​

上面的配置信息中，有提到一个 indexName，这里需要填写应用的一个索引名称。

进入创建好的应用，在左侧菜单栏中找到 Search，点击进入

图 6

进入之后，如下图所示。图中是已经创建好索引了，如果没创建，会提示创建，按步骤创建即可。

图 7

私钥放在 Github Secrets 中 ​

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

图 15

创建 crawlerConfig.json ​

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

json
{
    "index_name": "jacinda", // 填写自己的索引名称
    "start_urls": ["xxxxx"], // 填写自己的网站地址
    "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 文件（名称可更改，自定义），粘贴如下内容：

javascript
name: algolia
on:
  push:
    branches:
      - master
jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - name: Sleep for 120s
        run: sleep 120
      - 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 }}

解释一下：这里 yml 就是使用 Github Actions 在 Docker 中执行的 AlgoliaDocSearch scraper action，当我们推送到 main 分支时就会立即执行这个任务

以上是引用参考文档的博主说的解释说明

⚠️ 这里需要注意的是，由于git分支用的是 master，所以 branches 这里的值，就是 master. 如果你的分支用的是 main，请修改 branches 的值即可

本文主要是对 VitePress 添加搜索功能做一个归档，因为每个博主写的配置都不太相同，导致添加了搜索之后，无法搜索内容。所以，以上的爬虫配置，及脚本内容，是已经可以能搜索出内容的。

Copyright © 2023-present Jacinda