asciidoc_workflow.adoc

Use of the asciidoc format

The asciidoc format has been used for this documentation.

To use asciidoc format, ensure that the asciidoctor tool is installed (and on your system $PATH). Also, it can be useful to ensure your editor understands the filetype, e.g. for Vim you can install vim-asciidoctor.

A quick reference for asciidoc formatting can be found here.

This documentation follows the asciidoc recommended practice of One Sentence Per Line. If you choose to contribute (thank you!) please try and continue this practice to make future editing more straightforward.

Generating index.html for static web hosting

You can generate an index.html file for static web hosting by installing the [asciidoctor] tool and then running:

asciidoctor index.adoc

Simply host index.html along with the images/ directory and its contents at the root of your web server to serve the documentation.

Adding mermaid diagrams

If you add a mermaid diagram to an article, you must add:

:mermaid-puppeteer-config: ./puppeteer-config.json

To the header of the file, in order that the Container/Dockerfile can have mermaid-cli pass the puppeteer config to puppeteer.

Regenerate mermaid diagrams

In order to regenerate the mermaid diagrams, you will need mermaid-cli and asciidoctor-diagram installed.

With both of the above programs on your PATH, you can then run command:

asciidoctor -r asciidoctor-diagram index.adoc

To generate index.html, along with required images in the /images sub-directory.

Update index.html automatically as a pre-commit hook

If you prefer you can write a simple pre-commit hook to update index.html file automatically at each commit. An example of this might be:

$PROJECT_ROOT/.git/hooks/pre-commit

#!/usr/bin/bash

asciidoctor index.adoc