Maven Plugin 3.x.x Migration Guide

The asciidoctor-maven-plugin 3.0.0 introduces some breaking changes. This guide will provide the steps required to update a project currently using 2.x.x version. For each of the breaking changes, the motivation and new equivalent configuration will be offered.

New configuration details are highlighted in bold.

Motivations

Changes in this version have been motivated to improve the plugin evolution and maintenance. With that goal in mind, the single project that contained both the maven plugin and site integration components has been split into different maven submodules. The main advantage for most users is that usage of the asciidoctor-maven-plugin will not require downloading Doxia dependencies.

Users of the site module see v3 migration guide for site module.

Changes

Minimal Java version

Minimal Java version is 11.

For anyone in need of a Java 8 compatible release, v2.5.x of the plugin will be supported for some time after v3.0.x release. Note this also imposes versions on dependencies, for example:

  • Only AsciidoctorJ v2.5.x

  • Only asciidoctorj-diagram previous v2.2.8

Minimal AsciidoctorJ version

Support for AsciidoctorJ v1.6.x (released 14th Feb, 2019) has been totally removed and will fail when configured. This simplifies the current plugin code and allows for removal of Java reflection usage.

If you are setting the AsciidoctorJ dependency directly, ensure it’s v2.0.0 or higher.

invalid configuration
 <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.1.1</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj</artifactId>
            <version>1.6.2</version>
        </dependency>
    </dependencies>
</plugin>

Replace deprecated option 'headerFooter' by 'standalone'

headerFooter option in Asciidoctor has been replaced by the easier to understand standalone. The plugin aligns with that change replacing the option with standalone in the <configuration> block. The new option works exactly the same with the same semantics.

If you are using headerFooter option, just replace it with standalone.

invalid configuration
 <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
      <headerFooter>false</headerFooter>
    </configuration>
</plugin>
new configuration
 <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
      <standalone>false</standalone>
    </configuration>
</plugin>