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:

Additionnaly each component of the DevOps stack as a sub-documentation in the DevOps Stack Module section to better separate their specific documentation (in terms of maintenance and readability).

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.