Tips about algolia

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

Create algolia Application

1. Register algolia account
2. Create an application in algolia, such as fixit-blog
3. Select the application fixit-blog => Click Data Sources => Click Indices => Click Create Index
4. Create an index, such as index.en
5. 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.

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

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

2. 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

3. 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!