buildbricks/antora-lunr

Integration of Lunr in Antora

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)
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 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

Testing this module

In the root of the repository, run npm t.