Configure the Plugin

You can use the antora extension block to customize the antora commandline string that the plugin builds to run Antora. You can use the node extension block to configure the Node.js runtime, including the version of Node.js and npm.

Antora configuration block

The antora block is automatically available after you apply the plugin to your project. Here’s an example of the antora extension block that shows most of the configurable properties:

build.gradle
plugins {
    id 'org.antora' version '1.0.0' (1)
}

antora { (2)
    version = '3.0.3' (3)
    playbook = 'local-antora-playbook.yml' (4)
    options = [clean: true, fetch: true, stacktrace: true] (5)
    environment = [ (6)
        SEARCH_API_KEY: '123456',
        GOOGLE_ANALYTICS_KEY: 'abcxyz'
    ]
    packages = [ (7)
        '@antora/collector-extension': 'latest'
    ]
}
1 The Antora plugin must be declared in the plugins block at the top of your build script for the antora block to be available.
2 Use of the antora extension block is optional. If you don’t configure any properties in the antora block, the plugin will run Antora using default values.
3 Optional version property the specifies the version of Antora the plugin should install and run. The default version value is the latest stable release. The value can be an exact version ('3.2.0-alpha.2'), version tag ('testing'), or version range specifier ('~3.1'). Enclose the value in single quotes.
4 Optional playbook property that specifies the filesystem path to the Antora playbook file relative to the current working directory. The default value is 'antora-playbook.yml'.
5 Optional options property that specifies an array or map of additional Antora CLI options for the plugin to pass to the antora command. If the value is a map, the keys will be used as the option names (e.g., stacktrace becomes --stacktrace). If the key ends in s, the value can be an array, which is then converted into multiple occurrences of that option. If the key is attributes, the value can be a map, which is then converted into multiple attribute options. The default value is [] (or [stacktrace: true] if Gradle is run with --stacktrace)
6 Optional environment property that specifies an array of additional Antora environment variables. The default value is [:].
7 Optional packages property that specifies any additional Node.js Antora and Asciidoctor extension packages the plugin should install. The default value is [:]. The value isn’t used if package.json is present. If the package name begins with @, enclose the name in single quotes ('@antora/collector-extension'). See Package Management for usage examples and alternative dependency management options.

Here’s an example of how to pass multiple --attribute options to Antora using the map form of the options property:

build.gradle
antora {
    options: [
        attributes: [product: 'The Product Name', 'docker-tag': 'current']
    ]
}
Values that contain spaces do not need to be enclosed in a secondary set of quotes.

Any properties that aren’t set are assigned their default value at runtime.

Configuration reference

The antora extension block accepts the properties listed in the table below.

Property Default Values Notes

version

Latest stable version of Antora

exact version (3.1.0),
version tag (latest) or
version range specifier (~3.1)

The version of Antora the plugin should install and use to build the site.

playbook

antora-playbook.yml

Filesystem path (String) or file("path") (java.io.File)

The path is relative to the current working directory. Also see Playbook Provider for using a centrally-managed, author-oriented playbook template.

options

[] or [stacktrace: true] if Gradle
is run with the --stacktrace flag

Array or map of Antora CLI options. Array entries use the form '--name=value', whereas map entries use the form name: 'value'. If a map key ends with s, the value must be an array of values, representing multiple occurrences of the option.

See CLI Options for available options and their values.

environment

[:]

Map of Antora environment variables in the form name: value

The variables are set on top of System.getenv(). See Environment Variables for available variables and their values.

packages

[:]

Map of Node.js packages in the form name: version, where name is the package name in the npm registry and version is an exact version, version tag, or range specifier

If the package name begins with @, enclose the name in single quotes ('@antora/collector-extension'). See Package Management to learn more.

The antora extension block also provides a nested block named playbookProvider to configure the location of an external playbook to retrieve. See Playbook Provider to learn more.

Node configuration block

The Antora plugin configures the Node.js plugin to automatically provision a Node.js runtime. The Node.js plugin provides the node extension block, which you can use to control which Node.js runtime is selected and which directories it uses.

There’s no need to apply the Node.js plugin to enable this block since the Antora plugin already applies it.

Configure the Node.js version

The version of Node.js selects depends on what version of Node.js is specified in the node block. If no version is specified, the plugin will automatically look up and use the greatest Node.js LTS version. If you’re fine with using the greatest Node.js LTS release, then there’s nothing you need to do.

It’s possible to override the Node.js version using the node block in the Gradle build script. The property accepts the following syntax:

  • exact Node.js version (e.g., 18.13.0)

  • a fuzzy Node.js version (e.g., 19 or 19.4)

  • the keyword lts

  • the keyword latest

The plugin uses the data file located at nodejs.org/dist/index.json to resolve Node.js release versions. It looks for updates to this file once a day. In the interim, the file is cached in the .gradle folder.

Here’s an example of how to specify an exact Node.js version:

build.gradle
node {
    version = '18.13.0'
}

Here’s an example of how to use the latest version of Node.js listed in the dist data file:

build.gradle
node {
    version = 'latest'
}

Alternately, you can configure the plugin to use whatever version of Node.js is available on your PATH (i.e., in a directory listed in the PATH environment variable). To do so, set the download property to false:

build.gradle
node {
    download = false
}

When download is false, the version property is ignored. The plugin will not attempt to download and provision a Node.js runtime.

You can also use this block to configure other Node.js and npm settings.