The html sources of the tutorial website can be found inside the directory docs. This directory is linked to the github pages website. Any changes inside the directory docs will be picked up immediately on the tutorial website.

The site is published using Antora, a static site generator leveraging the AsciiDoctor text processing and publishing toolchain. Instructions on how to publish and possibly extend the site are given below:

First of all, install all needed prerequisites:

Make sure you have git installed on your system.

If you don't have git installed yet, download and run the Git installer.

For various installation tasks, we need npm, the Node.js package manager. If you don't have npm installed yet, download and run the Node.Js(r) installer. This installer will install both Node.Js and the package manager npm on your system.

With git and node installed, you're ready to set up the project.

First, clone the project into a local directory of your choice and enter this directory:

The project uses a customized version of the Antora Default UI as GUI template for the tutorial website. In order to successfully publish the tutorial site, we have to build and bundle this user interface first. Enter the directory www\ui of the cloned repository and install the dependencies using npm first. Afterwards, issue two gulp commands to generate the bundled user interface:

If all went fine, you should now see the UI bundle ui-bundle.zip available inside the subdirectory build.

• The directory www\asciidoc\modules\ROOT\pages contains the pages sources in asciidoc format. Extend and or alter these pages according to your needs.
• The directory www\asciidoc\modules\ROOT\assets contains the images of the pages and the attachments the pages link to. Extend and or alter these resource files as needed.

Using the antora publisher, we can now build the tutorial site. Enter the directory www\antora of the cloned repository and install the dependencies using npm first. Afterwards, issue the following antora command to generate the tutorial site:

If all went fine, you should now see your changes reflected in the web site stored inside the the subdirectory docs of the cloned repository.

Besides the html sources, you may want to generate a pdf version of the tutorial website. While there are several ways to produce a pdf document from asciidoc sources, we found out that leveraging the LaTeX toolchain gave the best results. All needed files for pdf generation are found inside the directory www\pdf. Be aware that generating high quality pdf documents is not an easy task, so don't expect a perfect result here.

PDF generation is done using a two step approach: first we produce docbook output from the asciidoc sources using the asciidoctor text processor. Afterwards, we use the pandoc document converter to convert the docbook source to a pdf document using xelatex as pdf engine. Instructions on how to a generate a pdf version of the tutorial site are given below:

First of all, install the needed prerequisites:

Make sure you have ruby installed on your system.

If you don't have ruby installed yet, download and run the Ruby installer.

Next, you have to install asciidoctor using the following command:

Download and run the Pandoc installer if you don't have pandoc installed on your system yet.

Make sure you have xetex installed on your system.

If you don't have xetex installed yet, install a working LaTeX installation on your system. For that purpose, you may make use of the MiKTeX or proTeXt or TeX Live distributions.

Now that you have asciidoctor, pandoc and xetex installed, you're ready to generate the pdf of the tutorial site.

Enter the directory www\pdf of the cloned repository and invoke asciidoctor text processor to produce docbook output from the asciidoc sources:

This will produce a file Tutorial.xml inside the same directory, containing docbook output.

Finally, invoke pandoc converter to generate a pdf file from the docbook output you just generated:

This eventually will produce the pdf file Tutorial.pdf inside the same directory.

For pdf styling, we use the pandoc LaTeX template authored by Pascal Wagler. Further customization of the generated pdf can be achieved by extending the metadata file metadata.yml.