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

Prerequisites

The extension uses the Antora container to build the site. You will thus need a working container runtime, such as Docker or Podman. If you can run tests with Testcontainers then this extension should work flawlessly for you.

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.0.2</version>
</dependency>

Example

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".

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