ggrossetie/antora-lunr

By ggrossetie

Updated almost 4 years ago

Image

5.7K

Antora Site Generator With Lunr

This site generator is a copy of the default site generator that in addition produces a Lunr index that can be used in your documentation UI. Lunr provides a great search experience in your documentation site without the need for external, server-side, search services.

Antora is a modular static site generator designed for creating documentation sites from AsciiDoc documents. Its site generator pipeline aggregates documents from versioned content repositories and processes them using Asciidoctor.

Getting Started

Prerequisites

In order to run this container you'll need docker installed.

Usage

Generate a site using a specific playbook

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t ggrossetie/antora-lunr:latest site.yml

In the above example, we generate a site using a playbook file named site.yml. You can also specify a playbook file using a relative path (i.e., path/to/site.yml).

Note: If you do not specify a playbook file, the container will try to build a site using a playbook file named antora-playbook.yml.

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t ggrossetie/antora-lunr:latest

The above command will build a site with Antora using a playbook file named antora-playbook.yml.

Generate a site using additional CLI options

You can add any option supported by the Antora CLI. In the following example we are using --attribute and --stacktrace.

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t ggrossetie/antora-lunr:latest --attribute foo=bar --stacktrace site.yml

Override antora command

By default, the container is using the following command:

$ antora --generator antora-site-generator-lunr

If for some reason you want to overidde this command you can use the --entrypoint option:

$ docker run -u $(id -u) -v $PWD:/antora:Z --rm --entrypoint="" -t ggrossetie/antora-lunr:latest antora --version

In the above example, we reset the container entrypoint using --entrypoint="" and then we can provide our own command. In this case, we are using the command antora --version.

Node modules

Node modules are installed in /usr/local/share/.config/yarn/global/node_modules.

As a result, the supplemental_ui directory from the npm package antora-lunr is available at:

/usr/local/share/.config/yarn/global/node_modules/antora-lunr/supplemental_ui

You can use this path to enable the search component in the default UI using the following definition in your playbook:

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: /usr/local/share/.config/yarn/global/node_modules/antora-lunr/supplemental_ui

Environment Variables

The image sets DOCSEARCH_ENABLED=true and DOCSEARCH_ENGINE=lunr environment variables. When executing docker run, you can overwrite any variable defined in the image using the -e, --env, or --env-file flags.

Versioning / Tags

  • latest: latest version of the Antora Lunr site generator running the latest version of Antora
  • <antora-version>: latest version of the Antora Lunr site generator using the specified version of Antora
  • <antora-version>-lunr<project-version>: Specific version of the Antora Lunre site generator using the specified version of Antora

License

MIT License. See License for more details.

Docker Pull Command

docker pull ggrossetie/antora-lunr