Search with Algolia

Algolia is an external cloud-based search engine for working with large volumes of data. Integrates with the Diplodoc documentation frontend.

Source code and additional instructions for the Algolia extension:
https://github.com/diplodoc-platform/algolia-extension

A VPN may be required to register an Algolia account.

Quick start

1. Register with Algolia
   Go to algolia.com and create an account. After that, obtain the App ID, Write API Key, and Search API Key for your application.
   (For details, see the section “Algolia registration and settings”)

2. Install the Diplodoc CLI and the Algolia extension (globally)

   npm install -g @diplodoc/cli
   npm install -g @diplodoc/algolia-extension
   

   (For more details on installation options, see the section “Installation”)

3. Configure search in .yfm
   In the root .yfm, specify:

   search:
     provider: algolia
     appId: <your app id>
     searchApiKey: <your search key>
     index: true
   

   (For an example with advanced settings, see “Example of advanced settings”)

4. Pass the keys and run the build
   For a secure build, pass the Write API Key via the CLI flag:

   yfm build -i ./docs -o ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia-extension" --api-key "your-write-key"
   

Algolia registration and settings

1. Register at algolia.com (a VPN may be required).
2. In the Algolia panel, create an application and obtain:
   • App ID ― application identifier
   • Write API Key ― secret key for data indexing
   • Search API Key ― key for client-side search
3. The index name (indexName) can be left unset; by default it is "docs".

Installation

There are two ways to install the Algolia search extension:

• Global installation — suitable for most typical scenarios if you simply want to build documentation with cloud search support.
• Local installation in the repository — recommended if you use custom plugins, modify the CLI, or work in a team with a shared package.json.

Global installation:

npm install -g @diplodoc/cli
npm install -g @diplodoc/algolia-extension

Running the build with the extension:

yfm build -i ./docs -o ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia-extension" --api-key "your-write-key"

Local installation in the @diplodoc/cli project:

npm install @diplodoc/algolia-extension

Running the build with the extension:

npm start -- -i ./docs -o ./docs-out --extensions @diplodoc/algolia-extension --api-key "your-write-key"

Sources for passing parameters

Extension parameters can be set via the CLI, environment variables, and the .yfm file:

Example of advanced configuration

search:
  provider: algolia
  appId: <your app id>
  indexName: docs
  index: true
  searchApiKey: <your search api key>
  indexSettings:
    searchableAttributes:
      - title
      - content
      - headings
      - keywords
    attributesToHighlight:
      - title
      - content
  querySettings:
    hitsPerPage: 10
    attributesToRetrieve:
      - title
      - content
      - url
      - section

Build and indexing

• By default, the extension creates local indexes in the _search directory of your output folder. These indexes are available for local search and are not uploaded to the cloud.
• If the config specifies the index: true parameter (or the CLI flag --index is used), then with each documentation build the index will not only be generated locally but also automatically uploaded (updated) to Algolia after the build.
• If you want to separate these processes — for example, build the documentation first, verify the result, and upload the index only after final verification or separately on a schedule — configure the build without the index parameter (or explicitly with index: false). Then only local indexes are created during the build. Later, to upload or update the index to the cloud, use a separate command:

yfm index -i ./docs-out --extensions "$(npm root -g)/@diplodoc/algolia-extension" --api-key "your-write-key"

Frequently asked questions and issues

• Search does not work — check that searchApiKey is correctly passed in the config.
• Indexing error — check the correctness and method of passing the write apiKey.
• Data does not appear in Algolia — make sure the index: true parameter is set in the config or the --index flag is used when running.