write_documentation.adoc

Contribute to documentation

The documentation of this project is located into the docs/ folder.

Create a new Documentation page

Write a new page

To write a new page of documentation, create a new file inside the docs/modules/ROOT/pages subfolder, with the .adoc extension. You should then write your content using Asciidoc language.

Tip	Use the AsciiDoc Syntax Quick Reference and the Asciidoc Cheatsheet

Convert an existing Markdown document

Alternatively, if you have an existing Markdown document, you can convert it using the pandoc tool.

Pandoc call to convert Markdown into Asciidoc, preserving format.

pandoc -f markdown -t asciidoc --wrap=preserve --shift-heading-level-by=-1 --standalone --output=FILENAME.adoc FILENAME.md

Include the new page

To include your page in the resulting website, edit the docs/modules/ROOT/nav.adoc file to add an index entry under the right section.

* Section
** xref:module_name:my_documentation_under_Section.adoc[My documentation's title]

Viewing your changes locally

You can generate the doc using the docker image of antora and put it in a local directory. For example with the following:

cd devops-stack
docker run --rm -it --user $(id -u) -v $PWD:/tmp/docs \
-e FORCE_SHOW_EDIT_PAGE_LINK=true -e CI=true \
docker.io/antora/antora:2.3.4 generate /tmp/docs/antora-playbook.yml \
--to-dir /tmp/docs/docs/output --cache-dir=./.cache

Then to visualize your result you can open your browser with the following command:

xdg-open file://$PWD/docs/output/index.html

Note	The environment variables FORCE_SHOW_EDIT_PAGE and CI are only needed if you want to check that the link "Edit this Page" is correct on each page. This is not automatic on private repositories, see https://docs.antora.org/antora/2.3/playbook/content-edit-url