Building Docs and Website

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


The prerequisites to install are:

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


To create/update documentation, we strongly recommend:

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.


The 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 -h to view options. The lower case flags skip steps, while the upper case flags exclude all steps except those indicated:


    builds everything and serves up the site

  • -AS

    runs only Antora generation and serves up the site

  • -ekcdl

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

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