Asciidoctor-maven-plugin 2.x.x migration guide

The 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.

1. Motivations

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. Changes

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.

new configuration
<configuration>
    <attributes>
        <imagesdir>images</imagesdir> (1)
    </attributes>
</configuration>
1 Note the attribute is all in lowercase.

2.3. Removal of sourceHighlighter

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:

new configuration
<configuration>
    <attributes>
        <source-highlighter>coderay</source-highlighter> (1)
    </attributes>
</configuration>
1 Note the attribute contains a hyphen.

2.4. Removal of attributeMissing and attributeUndefined

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.

new configuration
<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 templateDirs

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 template_dirs. Following this change the plugin configuration <templateDir> will be replaced by templateDirs. This will allow the use of multiple template directories.

previous configuration
<configuration>
    <templateDir>my-templates</templateDir>
</configuration>
new 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 html5. 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 <backend> element. If you are converting to DocBook, you will need to set it explicitly as follows.

backward compatible configuration
<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 src/main/asciidoc. 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/asciidoc and 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.