Antora Docs Package

Antora is a modular static site generator for creating documentation sites from AsciiDoc. This repository contains a simple Dockerfile to extend the official base Docker image for using Antora to generate the documentation pages of the DevOps Stack.

We extend the base image by adding two extensions:

• Antora Lunr Extension - an extension to add a full-text search powered by Lunr to navigate the documentation pages.

• Asciidoctor Kroki Extension - an extension for Asciidoctor.js to convert diagrams to images using Kroki.

This image is used by our workflow in the main repository to generate the documentation pages. You can also use it locally to preview documentation pages while writing them.

The following command allows you to generate the documentation pages:

docker run --rm -it --user $(id -u) -v $(pwd):/tmp/devops-stack -e FORCE_SHOW_EDIT_PAGE_LINK=true -e CI=true ghcr.io/camptocamp/devops-stack-antora:latest generate /tmp/devops-stack/antora-playbook.yml --to-dir /tmp/devops-stack/docs_test --cache-dir=/tmp/.cache

Important

This command needs to be run from the location where you have locally stored the main DevOps Stack repository, since that is where we store the antora-playbook.yml file and the main docs folder. You can run it from elsewhere as long as you replace $(pwd) and explicitly point to where you stored the DevOps Stack folder.

Release instructions

The image is built automatically as long as there is a tag added to this repository.

In order to do this, first make your modifications and commit them. After they have been merged to the main branch, you can then create and push a tag using the following steps:

git tag v3.1.2+devops-stack.1 # Use the correct versions instead of the ones in the example
git push --tags

Then, check if there is a new release available in the Packages section on this repository.