Tips about algolia

Lruihao included in Guides Documentation

2023-12-01 2024-01-01 About 700 words 4 minutes - views

Contents

Find out how to use algolia in the FixIt theme and update index automatically.

Create algolia Application

Register algolia ac count
Create an application in algolia, such as fixit-blog
Select the application fixit-blog => Click Data Sources => Click Indices => Click Create Index
Create an index, such as index.en
Click Settings => Click API Keys => Copy and save API Keys
- Application ID
- Search-Only API Key
- Admin API Key (please do not disclose it)

Application ID and Search-Only API Key are used for search configuration, and Admin API Key is used to automatically update the index.

Algolia in FixIt

Based on the API Keys obtained in the previous step, to configure the algolia search feature, you need to add the following content to the site configuration.

 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.en" # algolia index name
    appID = "" # algolia Application ID
    searchKey = "" # algolia Search-Only API Key

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

In order to generate index.json for searching, add JSON output file type to the home of the outputs part in your site configuration.

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

Upload Index

Then, you need to upload index.json files to algolia to activate searching. You could upload the index.json files by browsers but a CLI tool may be better. Algolia Atomic is a good choice.

Is your site multilingual?

To be compatible with Hugo multilingual mode, you need to upload different index.json for each language to the different index of algolia, such as zh-cn/index.json or fr/index.json…

Preparation

Please make sure you have installed Node.js.

Algolia Atomic Installation

If there is no package.json file in your project, please create one first.

1
npm init

Then install Algolia Atomic.

1
npm install atomic-algolia

Add the following content to the package.json file.

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

Usage

After you execute the hugo command to generate the site, you can use the following command to upload the index.json file to algolia to update the index.

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 index name
ALGOLIA_INDEX_FILE: local index.json file path

Automation

One more thing, you can automate the process of uploading index.json to algolia by using GitHub Actions

Add a ALGOLIA_ADMIN_KEY secret to your GitHub repository, the value is your algolia Admin API Key.

Add a .github/workflows/algolia-atomic.yml file to your GitHub repository, the content is as follows.

 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          

When you push your site to the master branch of the GitHub repository, GitHub Actions will automatically execute the hugo command to generate the site, and upload the index.json to algolia.

🎉 Now, everything is ready!