Documentation

Antora allows us to manage our documentation as code, which allow us to build our website the same way as we would build a software, store the code in a version control system and build/publish our documentation website using the same CI/CD principles as used for our softwares or our infrastructures.

Asciidoc is a lightweight markup language, similar to Markdown but offers more possibilites and more flexibility. It is higly configurable and allows to write documentation, articles, web pages, etc.

The website for our documentation can be automatically built and published on Github Pages using Github Actions.

The appearance of the website is externalized in an independant project and packaged as UI bundle. It can be highly adapted to ones needs and be can reused over multiple documentation projects.

We follow the Divio documentation structure to organize the documentation of this project, which is written in Asciidoc and built using Antora

In short, we break up the global documentation of the project in 4 parts, each of which being useful at a different time in the understanding or usage of the project:

There are overlaps between those elements, but respecting this separation prevents us from building a confused (and confusing) documentation.

To get a better overview of the Divio documentation structure, you can watch this interesting presentation by Daniele Procida

The UI for documentation sites created using Antora is externalized in a separated project named antora-ui, forked from antora-ui-default. This project produces an UI bundle containing all UI assets (CSS, Javascript, images, etc) using a gulp build script.

This UI bundle is linked to in the antora-playbook.yml of the documentation project and is dynamically pulled and loaded to render the resulting website during the buid phase.

There is a dedicated page that explains how to write and contribute to documentation.