Using Antora Locally

Installation

Prerequisites

You need to have these installed and set up:

Node.js (version 16 or later)

All following instructions will assume your working directory is the Git repository root of the root documentation project.

Installing dependencies

All dependencies for running Antora are specified and stored in package.json and package-lock.json . Installing these is straightforward using npm.

$ npm i (1)

1	Install all dependencies using NPM.

Antora should now be successfully installed.

The Antora documentation sets a great example and is a great resource to consult. It also provides excellent installation and running instructions..

Generating the site

In order for Antora to be able to generate our website, it requires a playbook which instructs and configures it.

Local playbook

For local development it makes sense to create a dedicated playbook optimized for that workflow. Let’s look at an example playbook file you could use.

Example 1. Antora playbook file for local development

antora-playbook-local.yml

site:
  title: Documentation
content:
  sources:
    - url: .
      branches: HEAD
      start_path: ./root_component
    - url: ../doc-writing-guide/ (1)
      branches: HEAD (2)
asciidoc:
  attributes:
    kroki-fetch-diagram: false (3)
    kroki-default-format: svg@
  extensions:
  - asciidoctor-kroki
output:
  clean: true
  dir: ./docs
urls:
  latest_version_segment: latest
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
  supplemental_files: ./supplemental-ui
antora:
  extensions:
  - require: '@antora/lunr-extension'

1	Content sources URLs can point to local instead of remote Git repositories.
2	For ease of use you can configure to only gather content from the `HEAD` of the currently checked out branch.
3	Pre-fetching Kroki diagrams can be disabled to vastly improve build speeds, and in the worst case prevent timeouts to the Kroki server.

Save the playbook file to the repository root and name it antora-playbook-local.yml^[1].

Antora will not pick up on the playbook file if the file extension is not exactly .yml, so be careful to avoid the use of the commonplace .yaml here.

Make sure you don’t check your local playbook file into the GitHub repository by adding it to the .gitignore file.

Running Antora to generate the site

With our playbook set up, we can now run Antora to generate the site.

$ npx antora antora-playbook-local.yml (1)
Site generation complete! (2)
Open file:///home/bart/Programming/Netbeheer-Nederland/docs/docs/index.html in a browser to view your site. (3)

1	Run Antora using the local playbook file.
2	If all goes well, the command should output `Site generation complete`.
3	The location of the site’s start page HTML file is echoed. You can open this file in your browser to view the site.

Although viewing the website by opening the start page file works okay, a better idea is to serve the site through HTTP using a simple server.

Serving the site

Now that the static HTML website has been outputted to the docs/ directory, let’s run the simple HTTP server http-server to serve the site locally.

$ npx http-server docs/ (1)
Starting up http-server, serving docs/ (2)

http-server version: 14.1.1

http-server settings:
CORS: disabled
Cache: 3600 seconds
Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  http://127.0.0.1:8080 (3)
  http://192.168.2.29:8080
Hit CTRL-C to stop the server (4)

1	Run a local HTTP server from the `docs/` directory.
2	The server log shows it’s running and echoes the location (`docs`) from which it serves content.
3	These are the URLs the server listens to, i.e. you can visit the website through these.
4	To stop the server, press `Ctrl`+`C`.

1. You could name this file something entirely different, but this is discouraged because it hinders interoperability with other software. One such example is the Asciidoctor IntelliJ plugin, which looks for filenames that contain the words `antora` and `playbook` in them.