Quarkus Antora

Features

  • Build, package and serve an Antora site from a Quarkus application

  • Edit the AsciiDoc files in Quarkus dev mode and the site is rebuilt upon browser reload

  • Test the generated Antora site

Prerequisites

The extension uses the Antora container to build the site. You will thus need a working container runtime, such as Docker or Podman.

Installation

To use this extension, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.antora</groupId>
    <artifactId>quarkus-antora</artifactId>
    <version>0.3.0</version>
</dependency>

Edit in Quarkus dev mode

The docs module in the source tree of Quarkus Antora may serve as a runnable example.

# Checkout the sources
$ git clone https://github.com/quarkiverse/quarkus-antora.git
$ cd quarkus-antora

# Build the whole project
$ ./mvnw install -DskipTests -Dquarkus.build.skip

# Change to docs module and start Quarkus in dev mode
$ cd docs
$ ../mvnw quarkus:dev
...
2024-04-11 18:26:56,703 INFO  [io.qua.ant.dep.AntoraProcessor] (build-3) Producing META-INF/antora/index.html
__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2024-04-11 18:26:57,010 INFO  [io.quarkus] (Quarkus Main Thread) quarkus-antora-docs 0.0.2-SNAPSHOT on JVM (powered by Quarkus 3.9.3) started in 3.829s. Listening on: http://localhost:8080

2024-04-11 18:26:57,011 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2024-04-11 18:26:57,012 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [antora, cdi, smallrye-context-propagation, vertx]

Once Quarkus has fully started, hit w to open the Antora site in browser. That should open http://localhost:8080/quarkus-antora/dev/index.html

Then edit some of the pages, for example

$ sed -i 's/= Quarkus Antora/= I love Antora/' modules/ROOT/pages/index.adoc

Go back to the browser, hit F5 to reload the page.

After that you should see the application being rebuilt and re-deployed in the console.

...
INFO  [io.qua.dep.dev.RuntimeUpdatesProcessor] ... Live reload total time: 1.151s

Then the page should get loaded with the new title "I love Antora".

optional attribute

Once you are done with editing, hit Q or CRTL+C to exit the dev mode.

Configuration

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.antora.image

The fully qualified name of the Antora container image to use for generating the documentation site. Example: docker.io/antora/antora:3.0.1

Environment variable: QUARKUS_ANTORA_IMAGE

string

docker.io/antora/antora:3.1.9