antora:antora Goal

Sets up a Node.js and npm installation, then installs and runs Antora from the current project with options defined in the plugin configuration using that Node.js runtime.

Plugin artifact

org.antora/antora-maven-plugin

Fully-qualified name

org.antora:antora-maven-plugin:1.0.0-alpha.4:antora

Default phase

antora (if plugin extensions are enabled), otherwise none

Requirements

Does not require a project
Does not require dependency resolution or collection
Does not require online

Summary

The antora:antora goal leverages the frontend-maven-plugin to install and run Antora from a Maven build. It also uses that plugin to automatically manage the Node.js installation needed to run Antora. To learn how to set up and configure this goal, refer to the following sections:

If your Antora site requires additional packages to build, refer to Package Management to learn how to declare those packages. The plugin will automatically install those packages before or when it runs Antora (depending on how they are declared).

This plugin configures Node.js to not use global module search paths (e.g., $HOME/.node_modules). The plugin will warn if it detects the existence of $HOME/node_modules, which is not a global module search path, but is always in the fallback module search path when the project is inside the user’s home directory.

Configuration parameters

The examples in this section show XML snippets that go inside the plugin declaration or one of its executions.

<environmentVariables>

Additional environment variables to set when invoking Antora. The name of the environment variable is specified using a tag name and the contents of that tag is the value.

The Antora process automatically inherits environment variables that are set at the time Maven is run. These additional environment variables take precedence over the inherited ones.

You can define the NODE_OPTIONS environment variable to set options passed to Node.js. (This plugin automatically appends --no-global-search-paths to the NODE_OPTIONS environment variable when running Antora). You can also use the environment variables to configure npm. Any environment variables that start with npm_config_ will be interpreted as an npm configuration parameter (e.g., npm_config_registry).

pom.xml

<configuration>
  <environmentVariables>
    <GOOGLE_ANALYTICS_KEY>UA-abcxyz-1</GOOGLE_ANALYTICS_KEY>
    <NODE_OPTIONS>--max-old-space-size=4096</NODE_OPTIONS>
  </environmentVariables>
</configuration>

Type: Map<String, String>
Required: false
Alias: env

<nodeDownloadUrl>

The root URL from where the Node.js distributions are retrieved. The trailing / is permitted, but not required.

pom.xml

<configuration>
  <nodeDownloadUrl>https://download.example.org/nodejs</nodeDownloadUrl>
</configuration>

CLI

$ mvn antora:antora -Dnode.downloadUrl=https://download.example.org/nodejs

Type: String
Required: true
Default value: https://nodejs.org/dist
User property: node.downloadUrl

<nodeDownloadServerId>

The ID of a Maven server declaration that supplies credentials for the URL from which Node.js distributions are downloaded (see the nodeDownloadUrl parameter).

pom.xml

<configuration>
  <nodeDownloadServerId>download-server</nodeDownloadServerId>
</configuration>

CLI

$ mvn antora:antora -Dnode.downloadServerId=download-server

Type: String
Required: false
User property: node.downloadServerId

<nodeExecutable>

The name or path of the Node.js executable to use.

When this parameter is specified, a Node.js installation structure will be created under the location specified by the nodeInstallDirectory parameter that links (using symlinks) to the Node.js installation for the specified executable. In this scenario, Node.js will not be downloaded and installed locally and the nodeVersion parameter will be ignored. The location of the Node.js installation is determined by passing a script to the specified executable that reports the location where Node.js is installed. The plugin validates the Node.js installation by looking for the npm binscript under lib/node_modules, node_modules, or libexec/lib/node_modules relative to the node executable (aka binary).

In order for the plugin to set up this link on Windows, developer mode must be enabled (so mklink can be used). If it isn’t, the plugin will copy the Node.js installation instead of creating symlinks to it.

pom.xml

<configuration>
  <nodeExecutable>node</nodeExecutable>
</configuration>

CLI

$ mvn antora:antora -Dnode.executable=node

Type: String
Required: false
User property: node.executable

<nodeInstallDirectory>

The location where Node.js (and npm) will be installed. The directory node, which contains the Node.js installation, will be created inside the specified directory.

pom.xml

<configuration>
  <nodeInstallDirectory>${basedir}</nodeInstallDirectory>
</configuration>

CLI

$ mvn antora:antora -Dnode.installDirectory=target

Type: File
Required: true
Default: ${project.build.directory}
User property: node.installDirectory

<nodeVersion>

The version of Node.js to install and use to run Antora. The goal also installs the version of npm that’s bundled with the specified version of Node.js.

Use lts to reference the most recent LTS release version. Use latest to use the highest available version. If the value is an exact version (e.g., v18.19.1), it will be used as is, bypassing the version resolution step. If the value is a single number (e.g., v18), it will be resolved to the latest minor and patch version of that major release. If the value has two segments (e.g., v18.19), it will be resolved to the latest patch version of that minor release. If the version cannot be resolved, it will default to a fallback version with a warning.

When the version is a number, the leading v is optional (e.g., 18).

pom.xml

<configuration>
  <nodeVersion>18</nodeVersion>
</configuration>

CLI

$ mvn antora:antora -Dnode.version=18

Type: String
Required: true
Default: lts (resolves to the most recent LTS release version)
User property: node.version

<options>

CLI options to pass to the Antora command.

If Maven is run with the --errors option, the stacktrace option is implicitly added first. If Maven is run from within a project, the to-dir ${project.build.directory}/site option is implicitly added as well.

The options can be specified as a comma-separated list (as long as no value contains a comma) or a list of nested <option> tags. (Technically, the name used for the nested tags does not matter, but the convention is to use the singular name of the parameter noun). The options are processed in the order specified.

If the option is a flag (aka switch), the form should be name, name? value, or name?=value. If a name? form is used, the value can be true, empty (which defaults to false), or false. The value can have an optional fallback value offset by a colon (e.g., ${property.name.here}:false) to override the default value when the primary part is empty. If the value resolves to false, it will not only skip adding the option, but also remove any option with that name if previously set.

If the option accepts a value, the form should be name=value or name value for singular options and name[]=value or name[] value for variadic options (options that can be specified multiple times, such as attribute, extension, and key). If a variadic option is specified using the singular form, all previous instances are replaced with the current one. Spaces and special characters in the value do not have to be escaped (as this escaping is handled internally).

Regardless of whether the option accepts a value, the name! form can be used to remove a previously set option with that name.

In all cases, the leading -- on the name part is optional. This prefix is automatically added to the options when passing them to Antora.

pom.xml

<configuration>
  <options>
    <option>fetch</option>
    <option>log-failure-level warn</option>
    <option>to-dir ${project.build.directory}/antora/site</option>
    <option>attribute[] product-name=ACME</option>
    <option>attribute[] product-url=https://example.org</option>
  </options>
</configuration>

pom.xml

<configuration>
  <options>fetch, log-failure-level warn, to-dir ${project.build.directory}/antora/site, attribute[] product-name=ACME, attribute[] product-url=https://example.org</options>
</configuration>

The user property for this parameter, antora.options, is only intented to be used when the goal is run outside of a Maven project.

Type: List<String>
Required: false
User property: antora.options

<additionalOptions>

Additional CLI options to pass to the Antora command. These options are appended to the options specified using the options parameter. The values are specified in the same way.

The intended use of this parameter is to add additional options in a non-default execution or from the command line without having to redefine all the options again.

If an additional option has the same name as an option defined using the options parameter, if it’s a singular option, it replaces the previous option, and if it’s a variadic option, it is appended.

pom.xml

<configuration>
  <options>
    <option>clean</option>
    <option>fetch</option>
    <option>log-failure-level warn</option>
    <option>log-format pretty</option>
  </options>
</configuration>
<executions>
  <execution>
    <id>graceful</id>
    <configuration>
      <additionalOptions>
        <option>log-failure-level fatal</option>
      </additionalOptions>
    </configuration>
  </execution>
</executions>

CLI

$ mvn antora:antora "-Dantora.additionalOptions=log-failure-level fatal"

When specifying a parameter using a user property, the property name must be followed by an equals sign (i.e., name=value). This differs from the syntax of an option, which permits the use of a space in place of an equals sign. If the value of the user property contains a space, the entire property declaration (i.e., the CLI option) must be enclosed in quotes. This enclosure is also necessary in PowerShell if the user property name or value contains a period.

Type: List<String>
Required: false
User property: antora.additionalOptions

<playbookFile>

The Antora playbook file to use. The value can be an absolute or relative path. If the path is relative, it’s resolved from the directory of the current Maven project (or the current working directory if Maven is run outside of a project).

pom.xml

<configuration>
  <playbookFile>src/main/antora/antora-playbook.yml</playbookFile>
</configuration>

Type: File
Required: true
Alias: playbook
Default: antora-playbook.yml
User property: antora.playbookFile

<playbookProvider>

Specifies the location of a playbook template to sideload or download to use as the Antora playbook. If this parameter is specified, the playbookFile parameter is ignored. The playbook template will be cached locally as provided-antora-playbook.yml.

See Playbook Provider to learn how to set up and use the playbook provider.

pom.xml

<configuration>
  <playbookProvider>
    <repository>org-name/repo-name</repository>
    <branch>docs-playbook</branch>
    <path>lib/per-branch-antora-playbook.yml</path>
    <tryLocalBranch>first</tryLocalBranch>
  </playbookProvider>
</configuration>

Type: org.antora.maven.PlaybookProvider
Required: false

<packages>

Specifies npm packages (aside from Antora itself) to install when installing Antora. These packages are not installed if a qualifying package.json file is present or the playbookProvider parameter is specified.

The packages can be specified as a comma-separated list (as long as no value contains a comma) or a list of nested <package> tags. Each package must be specified by its name and an optional version. (Technically, the name used for the nested tags does not matter, but the convention is to use the singular name of the parameter noun).

See Package Management to learn about how and when to use npm packages.

pom.xml

<configuration>
  <packages>
    <package>@antora/lunr-extension</package>
    <package>@asciidoctor/tabs@1.0.0-beta.6</package>
  </packages>
</configuration>

pom.xml

<configuration>
  <packages>@antora/lunr-extension, @asciidoctor/tabs@1.0.0-beta.6</packages>
</configuration>

The user property for this parameter, antora.options, is only intented to be used when the goal is run outside of a Maven project.

Type: List<String>
Required: false
User property: antora.packages

<additionalPackages>

Additional npm packages to install when installing Antora. These packages are appended to the packages specified using the packages parameter. The values are specified in the same way.

The intended use of this parameter is to add additional packages in a non-default execution or from the command line without having to redeclare all the packages again.

These packages are not installed when a qualifying package.json file is present. Unlike packages, these packages are installed if the playbookProvider is specified.

pom.xml

<configuration>
  <packages>
    <package>@asciidoctor/tabs</package>
  </packages>
</configuration>
<executions>
  <execution>
    <id>pdf</id>
    <configuration>
      <additionalOptions>
        <option>extension[] @antora/pdf-extension</option>
      </additionalOptions>
      <additionalPackages>
        <package>@antora/pdf-extension</package>
      </additionalPackages>
    </configuration>
  </execution>
</executions>

CLI

$ mvn antora:antora "-DadditionalOptions=extension[] @antora/pdf-extension" -DadditionalPackages=@antora/pdf-extension

Type: List<String>
Required: false
User property: antora.additionalPackages

<skip>

Controls whether the Antora site generation is skipped. If this parameter is set, the antora:antora goal will return immediately and not perform any work.

This parameter is typically only used when the antora:antora goal is bound to a common lifecycle phase and the user wants to skip the Antora site generation when that phase is included in the current Maven execution (i.e., build).

pom.xml

<configuration>
  <skip>true</skip>
</configuration>

CLI

$ mvn antora:antora -Dantora.skip=true

Type: boolean
Required: false
Default: false
User property: antora.skip

<version>

The version of Antora to install and use. The value can be an exact version (e.g., 3.1.7), a version tag (e.g., latest), or a version range specifier (e.g., ~3.1).

This parameter is ignored if packages are installed from packages.json unless those packages do not include the Antora CLI.

pom.xml

<configuration>
  <version>testing</version>
</configuration>

Type: String
Required: true
Default: latest

Individual options

Individual options may be specified on the command line using dedicated user properties prefixed with antora.option.. For multi-options, the name must be expressed in indexed form using a unique index (e.g., [0]) since user property names must be unique. For example:

$ mvn antora:antora -Dantora.option.clean \
  -Dantora.option.attribute[0]=product-name=ACME \
  -Dantora.option.attribute[1]=product-url=https://example.org

Here’s another example that shows how to configure Antora to print its version without generating the site:

$ mvn antora:antora -Dantora.option.version

Options specified this way take precedence over a matching option defined using the options or additionalOptions parameters.

User property precedence

In Maven, the user property for a parameter (e.g., -Dproperty.name=value) does not override the parameter set in the POM file. Consider the following scenario:

<configuration>
  <playbookFile>antora-playbook.yml</playbookFile>
</configuration>

Now let’s say you want to override the playbookFile property using its user property (antora.playbookFile) when calling Maven:

$ mvn antora:antora -Dantora.playbookFile=author-antora-playbook.yml

In this case, the user property is ignored. That’s because the parameter has already been defined in the POM, which has higher precedence. The user property value is only considered if the parameter is not defined in the POM.

(In contrast, an execution-level parameter will override/replace a plugin-level parameter with the same name).

However, there’s a way to invert this precedence. The technique is to define a user property in your POM. The value of the user property in the POM should have the default value you want to use in the plugin configuration. For example:

<properties>
  <antora.playbookFile>antora-playbook.yml</antora.playbookFile>
</properties>

Then, in the plugin configuration, reference this user property when assigning a value to the playbookFile parameter.

<configuration>
  <playbookFile>${antora.playbookFile}</playbookFile>
</configuration>

When using the user property name for the parameter, this step is not actually required, though it makes the behavior more clear.

Now, you can override the parameter value using the user property:

$ mvn antora:antora -Dantora.playbookFile=author-antora-playbook.yml

If you want, you can use a custom property name (e.g., user.antora.playbookFile) for this technique instead of using the same one mapped to the parameter.

This technique will only work when using basic parameters (i.e., parameters that are defined using a String value). But that’s why the goal offers the additionalOptions and additionalPackages parameters as an alternative.

Executions

When you configure a plugin, you typically use plugin-level configuration. That configuration can be further specialized using plugin executions. The configuration on a plugin execution is refered to as execution-level configuration.

You define a plugin execution either to call it directly from the CLI or to bind it to another phase. You can think of plugin executions as profiles for a single plugin.

Executions are specified using nested <execution> tags inside an <executions> tag in the plugin declaration. Each execution accepts an ID (the <id> tag) and a configuration (the <configuration> tag). The ID is used to identify or select an execution. The configuration adds or replaces parameters from the plugin-level configuration.

A good use case for a plugin execution is to specify parameters that are unique to the production build. Here’s an example:

<executions>
  <execution>
    <id>production</id>
    <configuration>
      <additionalOptions>
        <option>redirect-facility gitlab</option>
      </additionalOptions>
    </configuration>
  </execution>
</executions>

The plugin always has a default execution. The following table lists the ID of the default execution depending on which Maven command is used:

Command	Default Execution ID
antora:antora	default-cli
antora	default-antora

Command

Default Execution ID

antora:antora

default-cli

antora

default-antora

These IDs are important to know as you begin adding additional executions.

To run the plugin using a specific execution, append @<id> to the goal, where <id> is the value of the <id> tag. For example, to use the production execution, you would run the following command:

$ mvn antora:antora@production

In the log, you’ll see the antora:antora goal identified as (production) instead of (default-cli).

It’s not possible to specify the execution ID from the command line when running the antora phase. In that case, the execution ID will always be default-antora. However, it is possible to bind an execution to a phase so it will be used implicitly.

As an alternative, you can use Maven profiles to customize how a plugin is configured and used.