Building Docs and Website

The Apache Causeway website and documentation are written in AsciiDoc, using Antora as a static website generator.

Prerequisites:

The prerequisites to install are:

sudo apt install nodejs
sudo apt install npm

Antora (@antora/cli & @antora/site-generator-default), and Kroki (asciidoctor-kroki) for diagramming support:
```
npm i -g @antora/cli@^3.1.1 @antora/site-generator-default@^3.1.1 asciidoctor-kroki
```
See the Antora docs for details.
Serve (serve) for previewing:
```
npm i -g serve@^13.0.2
```

We also generate some AsciiDoc files dynamically from other source code. This requires:

Groovy 2.x

eg, using sdkman:
```
sdk install groovy 2.5.15
```
pandoc
```
sudo apt install pandoc
```
dos2unix
```
sudo apt install dos2unix
```

Authoring

To create/update documentation, we strongly recommend:

IntelliJ AsciiDoc plugin
IntelliJ Diagrams.net plugin

Even if you don’t use IntelliJ as your primary IDE, it’s worth using it for writing documentation - there’s currently nothing as good as the AsciiDoc plugin on any other editor platform, especially when it comes to writing Antora.

Build

The preview.sh script can be used to build the website, also calling the documentation tooling that automates documentation from code (the System Overview, large parts of the Reference Guide and the Configuration Guide).

Use preview.sh -h to view options. The lower case flags skip steps, while the upper case flags exclude all steps except those indicated:

preview.sh

builds everything and serves up the site
preview.sh -AS

runs only Antora generation and serves up the site
preview.sh -ekcdl

does the same thing, by skipping the other 5 steps.

The script can be found at the root of this git repo.