Setup of Antora
Documentation website configuration
The configuration of a documentation website consists of two types of components:
The configuration files are kept in a git repository. This repository can also contain content sources that are not tied to specific software repositories.
The sources for this section about the selection and setup of software components for a documentation system is kept within the repository for the site.
Components to specify the site
-
The supplemental ui provides files to be added to the user interface definition files.
-
They can override existing files, for instance to adapt templates used to generate pages.
-
They can also add files, for instance a CNAME instruction for Github Pages.
-
-
The styleguide provides additional files for other parts of the generation process.
-
The PlantUML config file is added in calls to the diagram rendering service to specify PlantUML styling.
-
A CSL file can be used to let Zotero generate bibliographies in the desired layout.
-
Components to generate and deploy the site
-
The package.json file (and associated lock file) are used to specify the versions of software components used.
-
The docker-compose.yml file lets you start local docker containers for the diagram rendering service.
-
The generator script specifies additional environment variables and selects the playbook to be used.
-
The Github Action provides a recipe to set up the diagram rendering service, install the required software components, run the generator script, and deploy the resulting site to Github Pages.