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 documentation 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 4 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.