Asciidoctor-maven-plugin 2.x.x migration guide
asciidoctor-maven-plugin 2.0.0 introduces some breaking changes.
This guide will provide the steps required to update a project currently using 1.5.x or 1.6.x version to 2.x.x.
For each of the breaking changes, the motivation and new equivalent configuration will be offered.
|New configuration details are highlighted in bold.|
Changes are mainly motivated to make the maven integration as seamless as possible with Asciidoctor. With that goal in mind most of the changes fall under one of these cases.
Align with Asciidoctor conventions and default values. Also, when possible aligning with other build solutions options like the gradle plugin or Antora.
Make clear distinction between Asciidoctor options and attributes. This simplifies the plugin’s code and projects' configuration avoiding ambiguities.
2.1. Removal of support for Java 7
From v2.x.x Java 8 will be the minimum required version. If you are forced to use Java 7, we recommend using the version 1.5.8 with AsciidoctorJ 1.6.2 for the most up to date features.
2.2. Removal of
imagesDir configuration and change of its default value
Related discussion: github.com/asciidoctor/asciidoctor-maven-plugin/issues/296
Until v1.5.8 it was possible to set the
imagesdir Asciidoctor attribute (asciidoctor.org/docs/user-manual/#setting-the-location-of-images) using the special
imagesDir configuration as follows.
<configuration> <imagesDir>my-images</imagesDir> </configuration>
Additionally, this configuration had as default value
images, which meant that you could just put your images inside a directory called like that.
However, this is a different behavior from default Asciidoctor (#setting-the-location-of-images) as well as other build tools like asciidoctor-gradle-plugin.
Version 2.0.0 will align with Asciidoctor removing the default value and encouraging the configuration of
imagesdir as any other attribute.
If you are relying on the default value, make sure to add the attribute as in the example.
<configuration> <attributes> <imagesdir>images</imagesdir> (1) </attributes> </configuration>
|1||Note the attribute is all in lowercase.|
2.3. Removal of
To avoid ambiguity between the configuration and attributes section, and make configuration more clear.
The configuration option
sourceHighlighter has been removed in favor of setting it as an attribute.
If you are using it, you will need to set it as follows:
<configuration> <attributes> <source-highlighter>coderay</source-highlighter> (1) </attributes> </configuration>
|1||Note the attribute contains a hyphen.|
2.4. Removal of
Related discussion: github.com/asciidoctor/asciidoctor-maven-plugin/issues/417
These options serve to modify behaviors related with attributes. From showing console warning messages, to removing lines of text amongst others.
If you are currently using these options, you will need to add them to the attributes section.
<configuration> <attributes> <attribute-missing>warn</attribute-missing> (1) <attribute-undefined>drop-line</attribute-undefined> </attributes> </configuration>
|1||Note both attributes contains a hyphen.|
2.5. Replacement of
templateDir (now deprecated in Asciidoctor) by
Related discussion: github.com/asciidoctor/asciidoctor-maven-plugin/issues/265
As stated in asciidoctor.org/docs/user-manual/#ruby-api-options
template_dir option is deprecated in favor of
Following this change the plugin configuration
<templateDir> will be replaced by
This will allow the use of multiple template directories.
<configuration> <templateDir>my-templates</templateDir> </configuration>
<configuration> <templateDirs> <templateDir>my-templates</templateDir> </templateDirs> </configuration>
2.6. Setting 'html5' as default backend
Related discussion: github.com/asciidoctor/asciidoctor-maven-plugin/issues/188
Current default backend is
docbook, contrary to Asciidoctor which is
This made sense back when the plugin was created because DocBook was the main scenario.
Nowadays the main usage is HTML conversion, so it makes sense to set
html5 as default backend.
This should reduce configuration for most users.
If you are converting to HTML, you won’t need to set the
If you are converting to DocBook, you will need to set it explicitly as follows.
<configuration> <backend>docbook</backend> </configuration>
|For advanced conversion needs, probably check antora.org/.|
2.7. Changing default sources directory
Related discussion: github.com/asciidoctor/asciidoctor-maven-plugin/issues/254.
Previous versions of the plugin search for AsciiDoc documents in
In case the folder does not exist, the plugin skips the execution.
This is being changed to a fallback mechanism where several paths are searched in specific order.
The new default value is
src/docs/asciidoc to reflect the difference in nature of AsciiDoc sources from executable code.
If the path does not exist,
src/main/asciidoc are searched for in that order.
This change does not break compatibility and has the advantage of following the same pattern as the asciidoctor-gradle-plugin, making easier to test both plugins.
3. AsciidoctorJ changes
Not part of the asciidoctor-maven-plugin, but important to consider during upgrade, the AsciidocotorJ extension API has suffered modifications.
These are simple and can be spotted with help of the IDE once the AsciidoctorJ dependency has been updated. Please, review them alongside the maven-plugin.