Using Antora for your open source documentation

Are you looking for an easy way to write and publish technical documentation? Let me introduce Antora — an open source documentation site generator. Simple enough for a tiny project, but also complex enough to cover large documentation sites such as Fedora Docs.

With sources stored in git, written in a simple yet powerful markup language AsciiDoc, and a static HTML as an output, Antora makes writing, collaborating on, and publishing your documentation a no-brainer.

The basic concepts

Before we build a simple site, let’s have a look at some of the core concepts Antora uses to make the world a happier place. Or, at least, to build a documentation website.

Organizing the content

All sources that are used to build your documentation site are stored in a git repository. Or multiple ones — potentially owned by different people. For example, at the time of writing, the Fedora Docs had its sources stored in 24 different repositories owned by different groups having their own rules around contributions.

The content in Antora is organized into components, usually representing different areas of your project, or, well, different components of the software you’re documenting — such as the backend, the UI, etc. Components can be independently versioned, and each component gets a separate space on the docs site with its own menu.

Components can be optionally broken down into so-called modules. Modules are mostly invisible on the site, but they allow you to organize your sources into logical groups, and even store each in different git repository if that’s something you need to do. We use this in Fedora Docs to separate the Release Notes, the Installation Guide, and the System Administrator Guide into three different source repositories with their own rules, while preserving a single view in the UI.

What’s great about this approach is that, to some extent, the way your sources are physically structured is not reflected on the site.

Virtual catalog

When assembling the site, Antora builds a virtual catalog of all pages, assigning a unique ID to each one based on its name and the component, the version, and module it belongs to. The page ID is then used to generate URLs for each page, and for internal links as well. So, to some extent, the source repository structure doesn’t really matter as far as the site is concerned.

As an example, if we’d for some reason decided to merge all the 24 repositories of Fedora Docs into one, nothing on the site would change. Well, except the “Edit this page” link on every page that would suddenly point to this one repository.

Independent UI

We’ve covered the content, but how it’s going to look like?

Documentation sites generated with Antora use a so-called UI bundle that defines the look and feel of your site. The UI bundle holds all graphical assets such as CSS, images, etc. to make your site look beautiful.

It is expected that the UI will be developed independently of the documentation content, and that’s exactly what Antora supports.

Putting it all together

Having sources distributed in multiple repositories might raise a question: How do you build the site? The answer is: Antora Playbook.

Antora Playbook is a file that points to all the source repositories and the UI bundle. It also defines additional metadata such as the name of your site.

The Playbook is the only file you need to have locally available in order to build the site. Everything else gets fetched automatically as a part of the build process.

Building a site with Antora

Demo time! To build a minimal site, you need three things:

  1. At least one component holding your AsciiDoc sources.
  2. An Antora Playbook.
  3. A UI bundle

Good news is the nice people behind Antora provide example Antora sources we can try right away.

The Playbook

Let’s first have a look at the Playbook:

site:
title: Antora Demo Site
# the 404 page and sitemap files only get generated when the url property is set
url: https://example.org/docs
start_page: component-b::index.adoc
content:
sources:
- url: https://gitlab.com/antora/demo/demo-component-a.git
branches: master
- url: https://gitlab.com/antora/demo/demo-component-b.git
branches: [v2.0, v1.0]
start_path: docs
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true

As we can see, the Playbook defines some information about the site, lists the content repositories, and points to the UI bundle.

There are two repositories. The demo-component-a with a single branch, and the demo-component-b having two branches, each representing a different version.

Components

The minimal source repository structure is nicely demonstrated in the demo-component-a repository:

antora.yml            <- component metadata
modules/
ROOT/ <- the default module
nav.adoc <- menu definition
pages/ <- a directory with all the .adoc sources
source1.adoc
source2.adoc
...

The following

antora.yml
contains metadata for this component such as the name and the version of the component, the starting page, and it also points to a menu definition file.

name: component-a
title: Component A
version: 1.5.6
start_page: ROOT:inline-text-formatting.adoc
nav:
- modules/ROOT/nav.adoc

The menu definition file is a simple list that defines the structure of the menu and the content. It uses the page ID to identify each page.

* xref:inline-text-formatting.adoc[Basic Inline Text Formatting]
* xref:special-characters.adoc[Special Characters & Symbols]
* xref:admonition.adoc[Admonition]
* xref:sidebar.adoc[Sidebar]
* xref:ui-macros.adoc[UI Macros]
* Lists
** xref:lists/ordered-list.adoc[Ordered List]
** xref:lists/unordered-list.adoc[Unordered List

And finally, there’s the actual content under modules/ROOT/pages/ — you can see the repository for examples, or the AsciiDoc syntax reference

The UI bundle

For the UI, we’ll be using the example UI provided by the project.

Going into the details of Antora UI would be above the scope of this article, but if you’re interested, please see the Antora UI documentation for more info.

Building the site

Note: We’ll be using Podman to run Antora in a container. You can learn about Podman on the Fedora Magazine.

To build the site, we only need to call Antora on the Playbook file.

The easiest way to get antora at the moment is to use the container image provided by the project. You can get it by running:

$ podman pull antora/antora

Let’s get the playbook repository:

$ git clone https://gitlab.com/antora/demo/demo-site.git
$ cd demo-site

And run Antora using the following command:

$ podman run --rm -it -v $(pwd):/antora:z antora/antora site.yml

The site will be available in the

public
directory. You can either open it in your web browser directly, or start a local web server using:

$ cd public
$ python3 -m http.server 8080

Your site will be available on http://localhost:8080.

Fedora Project community

4 Comments

  1. Love the use of podman and not dkxnet.!

  2. ojn

    Great post, you described the structure and process so clearly. The concept of virtual catalog is probably the most tricky part to grok for a newbie like me, thanks!
    Adopting those innovative solutions is one of the reasons on why I admire Fedora so much.

  3. NightRomantic

    Thanks for the interesting article!

    There’s formatting issue with paragraph “And finally, there’s the actual content…” Obviously it should be outside of

    ...

    block.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions

%d bloggers like this: