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.
To integrate Lunr in Antora, we need to modify the site generator pipeline.
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/cli@2.0.0
├── @antora/site-generator-default@2.0.0
└── npm@6.5.0
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
.
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 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
In the root of the repository, run npm t
.