关于 Algolia 的使用技巧

Lruihao 收录于相关教程主题文档

2023-12-01 2024-07-15 约 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。

关于 Algolia 的使用技巧

创建 Algolia 应用

FixIt 中的搜索配置

上传索引

准备

安装 Algolia Atomic

使用

自动化更新索引

相关内容