Spring Antora Maven Plugins

antora-component-version-maven-plugin

This plugin defines Maven properties that can be used for generating an antora.yml. The antora.yml can be included using the Antora Collector Extension.

• antora-component-version-maven-plugin Supported Attributes

• Configuring antora-component-version-maven-plugin

antora-component-version-maven-plugin Supported Attributes

Maven Property Name	Antora Key	Description
antora-component.version	version	Generates the Antora version attribute from the Maven version property by, if present, removing -SNAPSHOT.
antora-component.prerelease	prerelease	Generates the Antora prerelease attribute from the Maven version property: 1.0.0-SNAPSHOT will result in the prerelease attribute being set to -SNAPSHOT 1.0.0-M1 will result in the prerelease attribute being set to true 1.0.0-RC1 will result in the prerelease attribute being set to true 1.0.0 will result in the prerelease attribute being set to false

Configuring antora-component-version-maven-plugin

This section describes how to configure and use the antora-component-version-maven-plugin.

To start, define the plugin in your build:

pom.xml

<plugin>
    <groupId>io.spring.maven.antora</groupId>
    <artifactId>antora-component-version-maven-plugin</artifactId>
    <version>0.0.4</version>
    <executions>
      <execution>
        <goals>
          <goal>antora-component-version</goal>
        </goals>
      </execution>
    </executions>
</plugin>

Next, create a resource that will have Maven Filtering performed on it. The plugin adds the folder src/main/antora/resources as a filtered resource by default and we will use that location in our example. Alternatively, you can explicitly add Maven Filtering to any location and place it there.

Here is an example using the default location:

src/main/antora/resources/antora-resources/antora.yml

version: ${antora-component.version}
prerelease: ${antora-component.prerelease}
asciidoc:
  attributes:
    attribute-missing: 'warn'
# ... more attributes (possibly with values from other properties) as needed ...

Note	The folder antora-resources is used so that the Antora Collector Extension can import Antora resources without picking up any other resources your project may have (e.g. resources for your Java project).

Finally, you can generate the resource by invoking process-resources:

$ mvn process-resources; cat target/classes/antora-resources/antora.yml
...
version: 1.0.0
prerelease: -SNAPSHOT
asciidoc:
  attributes:
    attribute-missing: 'warn'

To use this with the Antora Collector Extension, you need to define the command in the collector configuration. For example:

antora.yml

name: data-commons
version: true
title: Spring Data Commons
nav:
  - modules/ROOT/nav.adoc
ext:
  collector:
    - run:
        command: mvnw -Pdocs process-resources
        local: true
      scan:
        dir: target/classes/antora-resources

antora-maven-plugin

This adds support for invoking Antora on Maven based projects by adding:

• antora Lifecycle - A new Maven lifecycle for building Antora projects.

• antora:antora - A goal named antora:antora that installs and invokes Antora

Note	See the Gradle Antora Plugin) for Gradle based projects.

antora Lifecycle

A Maven Plugin that adds a new Maven Lifecycle named antora that installs Antora and then builds an Antora project.

Phase	Description
pre-antora	A placeholder for processes that need to be performed before Antora is invoked.
antora	Executes Antora build by invoking antora:antora
post-antora	A placeholder for processes that need to be performed after Antora is invoked.

antora:antora

The goal antora:antora leverages mojo-executor to dynamically install run Antora from a Maven build.

• antora:antora Supported Attributes

• Configuring antora:antora

antora:antora Supported Attributes

Maven Property Name	Description	Example
<version>	The version of Antora to use. Default is 3.2.0-alpha.2	pom.xml <configuration> <environment> <version>3.1.4</version> </environment> </configuration>
environment	The optional environment element that contains additional environment variables.	pom.xml <configuration> <environment> <SEARCH_API_KEY>12346</SEARCH_API_KEY> <GOOGLE_ANALYTICS_KEY>abcxyz</GOOGLE_ANALYTICS_KEY> </environment> </configuration>
options	The optional environment element that contains additional Antora CLI options. The Default is --to-dir=target/antora/site, --stactrace	pom.xml <configuration> <options> <option>--log-failure-level=warn</log-failure-level> </options> </configuration>
node/version	The optional value of node to use to run Antora. The Default is v18.17.1	pom.xml <configuration> <node> <version>v16.16.0</version> </node> </configuration>
playbook	The Antora Playbook to use The Default is antora-playbook.yml	pom.xml <configuration> <options> <playbook>src/main/antora/antora-playbook.yml</playbook> </options> </configuration>
packages	The optional property that specifies any additional Node.js Antora and Asciidoctor extension packages the plugin should install. The Default is antora-playbook.yml	pom.xml <configuration> <packages> <package>@springio/[email protected]</package> </packages> </configuration>

Configuring antora:antora

This section describes how to configure and use antora:antora.

To start, define the plugin in your build within the root of a folder that contains your Antora files:

pom.xml

<plugin>
    <groupId>io.spring.maven.antora</groupId>
    <artifactId>antora-maven-plugin</artifactId>
    <version>0.0.4</version>
    <extensions>true</extensions>
</plugin>

Important

Ensure that you specify <extensions>true</extensions> to ensure that the custom lifecycle is also registered.

You can now invoke Antora using antora and view the results:

$ mvn antora
...
# view the results
$ tree target/antora/site -P '*.html'
├── _
│   ├── css
│   ├── font
│   ├── img
│   └── js
│       └── vendor
└── test
    └── 1.0.0-SNAPSHOT
        └── index.html