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.
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.
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:
- At least one component holding your AsciiDoc sources.
- An Antora Playbook.
- A UI bundle
Good news is the nice people behind Antora provide example Antora sources we can try right away.
Let’s first have a look at the Playbook:
title: Antora Demo Site
# the 404 page and sitemap files only get generated when the url property is set
- url: https://gitlab.com/antora/demo/demo-component-a.git
- url: https://gitlab.com/antora/demo/demo-component-b.git
branches: [v2.0, v1.0]
As we can see, the Playbook defines some information about the site, lists the content repositories, and points to the UI bundle.
The minimal source repository structure is nicely demonstrated in the demo-component-a repository:
antora.yml <- component metadata
ROOT/ <- the default module
nav.adoc <- menu definition
pages/ <- a directory with all the .adoc sources
title: Component A
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:ui-macros.adoc[UI Macros]
** xref:lists/ordered-list.adoc[Ordered List]
** xref:lists/unordered-list.adoc[Unordered List
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
$ cd public
$ python3 -m http.server 8080
Your site will be available on http://localhost:8080.