Antora: Documentation made simple

Compared to Markdown, Asciidoc has more relevant features. For example, we have the possibility to directly incorporate PlantUML (plantuml.com) diagrams. Because often, a picture says more than a thousand words. with Asciidoc, we can define our diagrams as code, making them easy editable. Take for example the two diagrams to the left and right.

Both are defined within this very document, and are editable. There is the possibility to also process PlantUML code with Jekyll through, for example, Jekyll-PlantUML (github.com), but we need to install a piece of software to compile the diagrams, and we need special syntax. With Asciidoc, the definition of a PlantUML is very similar to this of a code block:

We see that this, in deed, is quite similar to a code block. And the named anchor allows us to reference the image like this (<<plantuml-use-case, like this>>). Another nice feature are cross-references to other pages, e.g. to the index page.

Asciidoc has a lot more to offer. If you are not yet convinced, I recommend taking a look at the Writer’s guide (asciidoc.org). But enough about Asciidoc, let’s move on to the main event and look at Antora.

The job of antora is twofold. First, it bundles different Asciidoc together, and second it converts them to HTML pages.

Antora is driven by a concept of modules. To explain this in more detail, let us look at the structure of this repository at the time of writing. We start with the about-section of this blog:

The about directory is what is called a component in Antora. If we were use Antora to generate documentation for software components, we would have one Antora component per software component. The module is described in the antora.yml. Its content looks like this:

The interesting thing about the version is that Antora components must be in git repositories. We can have multiple versions of the same component, allowing us to have documentation to different version of our software components. We will see later how we can incorporate multiple versions of a component.

A component has directories to represent different modules. The standard module is called ROOT (which is the only module used in the about component). Within a module, we find more subdirectories, e.g.:

For an in-depth explanation, I recommend taking a look at the corresponding documentation at `docs.antora.org`.

Now let us look at the content of the navigation in nav.adoc.

The content of those files is always an unordered list. We can add non-navigational Top-level entries, which we will see soon.

I already said twice that we will "see things soon". To fulfill this promise, we will take a look at the video component, which is a bit more complex. We start again by looking at the file structure (since the articles component is empty and mostly similar to the videos component, we will skip it).

Directory structure is mostly the same, but now we have multiple modules (one module per year), and we see some nav.adoc`s in the `partials folder. Let us take a look at one of them.

We see something new here: the .2021. This is a Top level entry, and the following entries will be grouped under it. When we convert this navigation to HTML pages, it will look like shown in Figure 3. This is a nice way to keep the navigation organized. But what makes this a partial? To answer this question, we need to take a look at the nav.adoc of the module, located in ROOT/nav.adoc. The navigation files for the other components look similar.

In this file, we bind all partial navigations of all components together, giving us a single navigation for the whole module. The final result is shown in Figure 4. We can also see the uppermost entry Video, which is not mentioned in the nav.adoc. This is the name of this component, and automatically added by Antora.

As we can see, Antora tries its best to fit everything where it belongs. Since this part of the post is quite screenshot-heavy, I am not totally satisfied with the layout. on the other hand, for a minimal configuration approach, it is good.

At the start of this subsection, we said that antora has two jobs: binding different sources together, and converting them to HTML. Up until now, we have taken a look at the first part. We are still missing the "binding together" of all those components, and I also said that antora can pull in content from multiple repositories. And we have not yet talked about generating HTML pages. Fortunately, most of this is done through a single YAML file, the Antora playbook. For this page, we find the antora-playbook.yml in the root of the project. Let us take a look at its content to learn how it works.

While somewhat lengthy, the file is actually rather straight forward. The antora-block configures extensions to load. The site block configures the base setup for the page, most notably the start page. The syntax here is <component-name>::[<directory>/*]<file>. The ui-section configures the UI. Antora allows a great deal of customization through the supplemental_files directory. We will not discuss this here, but suffice to say: when I designed this blog, this was the part I spent the most time on 🙂. The asciidoc section configures everything necessary for Asciidoc. Here, we use it to add some attributes to all pages. A neat little trick is the page-pagination: true@ entry. The entry page-pagination controls whether the next- and prev-links at the bottom of the page are available. While I want them on most pages, I do want the flexibility to deactivate them on some pages. So the default is true and the @ at the end allows us to override it on a per-page basis.

Finally, there is the content section. This is the glue where all modules ar bound together. Each entry consists of a URL, a list of branches and a start path. The URL must point to a git repository. As we can see: it can point to the repository we are currently in. But it can also point to other repositories. This is the magic that allows us to bind together documentation from different repositories. A more complete example can be found in the Antora playbook for all quarkus quarkiverse documentations (github.com). The important part is: every component that has its own antora.yml must be listed here, with the URL pointing to the git repository it resides in, and the start_path holding the directory containing the antora.yml, relative to the directory.

We still have to actually generate the HTML pages from the Asciidoc documents. For this, we use npm (nmpjs.com). Initially, we have to install the Antora npm package. A guide can be found in The official Antora documentation (docs.antora.org). When we use Antora extensions, the extensions have be installed through npm. For the lunr extension, the installation command looks like this:

When the setup is done, we can build the pages by executing

The generated pages will be stored in build/site and are then ready to be deployed.

Yes. Much more. Antora is rich. I started looking into it about a week ago, and this blog is what I came up with since then. There are different UI themes, although I am quite satisfied with the current UI (only thing missing for me personally is a night mode toggle). I plan to use Antora for my personal projects. I also plan recommending it in customer projects. Having a centralized documentation of software modules is a tremendous benefit, especially for colleagues working in operations.

If you want to see Antora in action, used for its designed purpose, I recommend taking a look at The documentation page of the quarkiverse extensions (quarkiverse.github.io).