关于 algolia 的使用技巧

Lruihao 收录于教程文档

2023-12-01 2024-01-01 约 1100 字预计阅读 3 分钟 - 次阅读

了解如何在 FixIt 主题中使用 algolia，并自动化更新索引。

创建 algolia 应用

注册 algolia 账号
在 algolia 中创建一个应用（Application），例如 fixit-blog
选中应用 fixit-blog => 点击 Data Sources => 点击 Indices => 点击 Create Index
创建一个索引，例如 index.zh-cn
点击 Settings => 点击 API Keys => 复制保存 API Keys
- Application ID
- Search-Only API Key
- Admin API Key (请勿公开)

Application ID 和 Search-Only API Key 用于搜索配置，Admin API Key 用于自动化更新索引。

FixIt 中的搜索配置

根据上一步获取到的 API Keys，配置 algolia 的搜索功能，你需要在站点配置中添加以下内容。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
[params.search]
  enable = true
  type = "algolia"
  contentLength = 4000
  placeholder = ""
  maxResultLength = 10
  snippetLength = 30
  highlightTag = "em"
  absoluteURL = false
  [params.search.algolia]
    index = "index.zh-cn" # algolia 索引名称
    appID = "" # algolia Application ID
    searchKey = "" # algolia Search-Only API Key

为了生成搜索功能所需要的 index.json, 请在你的站点配置中添加 JSON 输出文件类型到 outputs 部分的 home 字段中。

1
2
[outputs]
  home = ["HTML", "RSS", "JSON"]

上传索引

然后你需要上传 index.json 到 algolia 来激活搜索功能。你可以使用浏览器来上传 index.json 文件，但是一个自动化的脚本可能效果更好，Algolia Atomic 是一个不错的选择。

你的站点是多语言模式？

为了兼容 Hugo 的多语言模式，你需要上传不同语言的 index.json 文件到对应的 algolia index, 例如 zh-cn/index.json 或 fr/index.json……

准备

请确保你已经安装了 Node.js。

安装 Algolia Atomic

如果你的项目中没有 package.json 文件，请先创建一个。

1
npm init

然后安装 Algolia Atomic。

1
npm install atomic-algolia

在 package.json 文件中添加以下内容。

1
2
3
4
5
{
  "scripts": {
    "algolia": "atomic-algolia"
  }
}

使用

当你执行 hugo 命令生成站点后，你可以使用以下命令上传 index.json 文件到 algolia 来更新索引。

1
ALGOLIA_APP_ID={{ YOUR_APP_ID }} ALGOLIA_ADMIN_KEY={{ YOUR_ADMIN_KEY }} ALGOLIA_INDEX_NAME={{ YOUR_INDEX_NAME }} ALGOLIA_INDEX_FILE={{ YOUR_FILE_PATH }} npm run algolia

ALGOLIA_APP_ID：algolia Application ID
ALGOLIA_ADMIN_KEY：algolia Admin API Key
ALGOLIA_INDEX_NAME：algolia 索引名称
ALGOLIA_INDEX_FILE：本地 index.json 文件路径

自动化更新索引

One more thing，你可以使用 GitHub Actions 自动执行将 index.json 上传到 algolia 的过程。

在你的 GitHub 仓库中添加一个 ALGOLIA_ADMIN_KEY 的 secret，值为 algolia Admin API Key。

在你的 GitHub 仓库中添加一个 .github/workflows/algolia-atomic.yml 文件，内容如下。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
name: Update Algolia Search Index

on:
  push:
    branches:
      - master
    paths:
      - "content"
  workflow_dispatch:

jobs:
  algolia-atomic:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
        with:
          submodules: recursive  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"
          extended: true

      - name: Build
        run: |
          npm install
          npm run build          

      - name: Update Algolia Index (en)
        env:
          ALGOLIA_APP_ID: YKOxxxxLUY # algolia Application ID
          ALGOLIA_ADMIN_KEY: ${{ secrets.ALGOLIA_ADMIN_KEY }} # algolia Admin API Key
          ALGOLIA_INDEX_NAME: "index.en" # algolia index name
          ALGOLIA_INDEX_FILE: './public/index.json' # local index.json file path
        run: |
          npm run algolia          

      - name: Update Algolia Index (zh-cn)
        env:
          ALGOLIA_APP_ID: YKOxxxxLUY
          ALGOLIA_ADMIN_KEY: ${{ secrets.ALGOLIA_ADMIN_KEY }}
          ALGOLIA_INDEX_NAME: "index.zh-cn"
          ALGOLIA_INDEX_FILE: "./public/zh-cn/index.json"
        run: |
          npm run algolia          

当你将你的站点推送到 GitHub 仓库的 master 分支时，GitHub Actions 将自动执行 hugo 命令生成站点，并将 index.json 上传到 algolia。