After 2 years of working with the arc42 template in markdown, I spent the last few weeks learning about an asciidoc based site generator named Antora. The main reason for the interest in AsciiDoc was the fact that the limited feature set in markdown often impairs you while writing down complex things. But I had one problem; most of our documentation is scattered across multiple repositories as we try to keep the docs as close to the code as possible. That is why this series will cover how to get a multi repository (software) architecture template up and running using Antora.

Figure 1. This is a screenshot of the final result

The starting point

There are a few things that you should at least have heard of before you continue reading:

AsciiDoc is a markup language, kind of like Markdown but more powerful. Think of it as a hybrid between the extremely powerful LaTeX and the simple but easy to read Markdown.

Compared to Markdown it focuses more on providing large documents like books or full blown documentation

You might also stumble upon Asciidoctor which is the de-facto standard for converting asciidoc files into readable formats like pdf, html, epub etc. whereas AsciiDoc itself is the markup syntax itself

arc42 is a software architecture template under MIT license that can be used in almost any scenario because it proves to be highly flexible and inherently agnostic of technology and domains

Antora solves the problem of writing AsciiDoc distributed over multiple repositories by introducing a component concept and providing a generator that merges the multiple sources automatically

The official arc42 asciidoc template is structured into the twelve arc42 chapters and one main file arc42-template.adoc which includes all the chapters as refernce to combine them into a kind of book.
The main conflict I had with this concept in my projects was that I want my lower level software architecture to be close to the implementation and - in my multi-repository environment - that means a different repository than the overall concepts that arc42 focuses on in the first chapters.

The first step to introduce Antora is to make your AsciiDoc files actually comply with the Antora way of structuring documentation.

Changing docs into the Antora structure

Note:

There are two types of abstraction that Antora makes for distributed documentation; Component and Module

A component can have multiple modules that are all located in a fixed directory structure adjacent to each other, there can be only one component within a git repository. Each component must have at least one module, the ROOT module.
The playbook (overall config of the documentation) references one or more git repositories that each contains a component with 1 or more modules.

Antora expects all documentation to be part of a component

any asciidoc file can reference or include files from other components within the same Antora project

the playbook can define multiple content sources

each content source needs to point to a root directory of a git repo (local or remote)

you can use start_path in a playfile source to make the docs start relative to the git root

Tip:

In case you want to publish to gh pages or any other service that might run jekyll take a look at these notes describing how to make antora work in a jekyll environment

Customizing the UI

I actually think Antora’s default UI is quite pleasing - compared to the default plantUML theme 🙄. But I wanted to modify their default footer content. For small changes Antora has a concept of supplemental UI files that allows you to switch individual files of the UI component that are used during the Antora site generation.

By taking a look at the default UI project I identified the footer-content.hbs as the file I wanted to replace.
This is achieved by the supplemental_files: ./supplemental-ui section in the playbook.yml and adding the custom footer file in the respective directory.

supplemental-ui/footer-content.hbs

<footer class="footer">
<p>Original arc42 template licensed under <a href="https://raw.githubusercontent.com/arc42/arc42-template/master/LICENSE.txt">MIT</a> and modified for antora fit by <a href="https://anoff.io">Andreas Offenhaeuser</a>, the page is created using the Antora Default UI licensed under <a href="https://gitlab.com/antora/antora-ui-default/blob/master/LICENSE">MPL-2.0</a> </p>
</footer>

In addition to this I added the Find on GitHub entry in the header, but I am sure you can figure out how that works 😉