ℹ️ Information ℹ️

The next major version of this project will be based on the pipeline extension feature (introduced in Antora 3) and become an official extension of the Antora project. As a result, the repository has been moved to its new home.

If you are preparing to migrate to Antora 3, then you should be testing the extension instead of the integration in this repository. Once Antora 3 is released, this repository will go into maintenance mode for users who have not yet transitioned from Antora 2 to Antora 3. After some time, the repository will be archived.

---

Integration of Lunr in Antora

Lunr provides a great search experience without the need for external, server-side, search services. It makes it possible to add an offline search engine in your Antora's documentation site.

Usage

Generate an index file

To integrate Lunr in Antora, we can either use a custom site generator pipeline that includes Lunr or modify your current site generator pipeline.

TIP: To make things easier, we provide a copy of the default site generator that in addition produces a Lunr index. Learn how to install and use this generator.

NOTE: The following instructions only apply if you are using the default pipeline. If you are using a custom pipeline, the logic remains the same but you will have to find yourself where the generateSite function should be added.

Antora provides a default pipeline named @antora/site-generator-default. Make sure that it's installed using the command npm list --depth 0. If you don't find the module in the result then it's probably installed globally. Add the -g flag and execute the command again:

npm list -g --depth 0
/usr/local/lib
├── @antora/[email protected]
├── @antora/[email protected]
└── [email protected]

As you can see in the example above, the module is installed globally in /usr/local/lib. The node_modules folder will be either at the root of your project or in your global libraries folder: /usr/local/lib/node_modules.

Once you've located the module, edit the file node_modules/@antora/site-generator-default/lib/generate-site.js adding after use strict:

const generateIndex = require('antora-lunr')

In the generateSite function add the following two lines after const siteFiles = mapSite(playbook, pages).concat(produceRedirects(playbook, contentCatalog)):

const index = generateIndex(playbook, pages, contentCatalog, env)
siteFiles.push(generateIndex.createIndexFile(index))

Install this module:

$ npm i antora-lunr

NOTE: If Antora is installed globally, you should also add this module globally using the -g flag:

$ npm i -g antora-lunr

When generating your documentation site again, an index file will be created at the root of your output directory, which depends on the value of output.dir in your playbook. For the default output dir, that will be build/site/search-index.js.

Enable the search component in the UI

Now that we have a search-index.js, we need to enable the search component in the UI.

Copy the supplemental_ui directory from the npm package node_modules/antora-lunr/supplemental_ui in your Antora playbook repository and configure a supplemental_files:

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  supplemental_files: ./supplemental_ui

NOTE: For this to function correctly you must provide the site.url key in your playbook file. See the Antora docs on the playbook schema. If using the site locally (not serving from a web server) then you can set your site.url to a file:// reference, e.g. file:///home/documents/antora/website/public/.

TIP: If you are using serve HTTP server to view your site locally, set the site.url to http://localhost:5000.

Generate the site

Generate your documentation site with the following environment variables:

• DOCSEARCH_ENABLED=true
• DOCSEARCH_ENGINE=lunr

For instance, as a command line:

$ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr antora site.yml

Configuration

Index only the latest version

To index only the latest (released) version, set the following environment variable:

• DOCSEARCH_INDEX_VERSION=latest

For instance, as a command line:

$ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr DOCSEARCH_INDEX_VERSION=latest antora site.yml

Support for other languages

By default, Lunr support only English language. You can add support for the following other languages:

• Arabic (ar)
• Chinese (zh)
• Danish (da)
• Dutch (nl)
• Finnish (fi)
• French (fr)
• German (de)
• Hindi (hi)
• Hungarian (hu)
• Italian (it)
• Japanese (ja)
• Norwegian (no)
• Portuguese (pt)
• Romanian (ro)
• Russian (ru)
• Spanish (es)
• Swedish (sv)
• Thai (th)
• Turkish (tr)
• Vietnamese (vi)

IMPORTANT: To use Chinese language, you need to install nodejieba dependency:

$ npm i nodejieba

To use one or more languages, set the DOCSEARCH_LANGS environment variable with all desired language codes (comma separated):

• DOCSEARCH_LANGS=en,fr

For instance, as a command line:

$ DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr DOCSEARCH_LANGS=en,fr antora site.yml

Testing this module

In the root of the repository, run npm t.

Who's using it

Here's a list of projects who are using Antora Lunr.
To add your project to this list, please edit this page!

• Uyuni Documentation
• SUSE Manager Documentation
• Commodore Components Hub (VSHN)