Skip to main content

How to use Search in Docusaurus with Algolia Docsearch

Introduction

I use Algolia Docsearch on this docs website. It is free to use on Algolia's Community plan, but you need to display Algolia's logo in your search console. Thank you Algolia! 🙏🏼

The official tutorial on how to self-host Algolia Docsearch can be found here. I use the crawler from the code base, but the Docker mode is probably easier.

Setup

When setting up the pipenv, I had some trouble running pipenv install. This command helped:

pipenv --python=/home/linuxbrew/.linuxbrew/opt/python@3.8/bin/python3

It was also helpful to change the required Python version in the Pipfile to the version I had. In my case, it was 3.8.5.

You can create your config file using their bootstrap or create one based off of the Docusaurus v2 config file.

As a result, my config.json is something like this:

{
"index_name": "theochu.com",
"start_urls": ["https://theochu.com/"],
"sitemap_urls": ["https://theochu.com/sitemap.xml"],
"sitemap_alternate_links": true,
"stop_urls": [
"https://theochu.com/blog",
"https://theochu.com/doc1",
"https://theochu.com/doc2",
"https://theochu.com/doc3",
"https://theochu.com/mdx"
],
"selectors": {
"lvl0": {
"selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
"type": "xpath",
"global": true,
"default_value": "Documentation"
},
"lvl1": "header h1",
"lvl2": "article h2",
"lvl3": "article h3",
"lvl4": "article h4",
"lvl5": "article h5, article td:first-child",
"lvl6": "article h6",
"text": "article p, article li, article td:last-child"
},
"strip_chars": " .,;:#",
"custom_settings": {
"separatorsToIndex": "_",
"attributesForFaceting": ["language", "version", "type", "docusaurus_tag"],
"attributesToRetrieve": [
"hierarchy",
"content",
"anchor",
"url",
"url_without_anchor",
"type"
]
},
"nb_hits": 1110
}

Run

If you have the config.json file in your root directory, run:

pipenv shell

then run

./docsearch run ./config.json

Make sure you have the ./ before config.json because ./ indicates the current directory. Running ./docsearch run config.json without the ./ will not work.

When you put the Algolia information into your docusaurus.config.js, make sure you put in the appId as well as the apiKey and indexName. You can see what I mean in this pull request or this commit for the pull request.

A live example of how to configure Algolia in docusaurus.config.js is available here:

  themeConfig: {
algolia: {
apiKey: 'f2899fea0369aeea336963e48a0e46dc',
indexName: 'standardnotes',
},