Wondering what’s next for npm?Check out our public roadmap! »

    @falconia/antora-lunr

    0.8.0-rc.1 • Public • Published

    Integration of Lunr in Antora

    Build Status npm

    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/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, 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)
    • Danish (da)
    • Dutch (nl)
    • Finnish (fi)
    • French (fr)
    • German (de)
    • Hungarian (hu)
    • Italian (it)
    • Japanese (ja)
    • Norwegian (no)
    • Portuguese (pt)
    • Romanian (ro)
    • Russian (ru)
    • Spanish (es)
    • Swedish (sv)
    • Thai (th)
    • Turkish (tr)
    • Vietnamese (vi)

    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.

    Install

    npm i @falconia/antora-lunr

    DownloadsWeekly Downloads

    23

    Version

    0.8.0-rc.1

    License

    MIT

    Unpacked Size

    126 kB

    Total Files

    18

    Homepage

    antora.org/

    Last publish

    Collaborators

    • avatar