Asciidoctor Maven plugin 1.5.0 released!

by Dan Allen -

Storm in Desert

The West may still be suffering from a dry spell, but we’re excited to shower Maven users with the release of version 1.5.0 of the Asciidoctor Maven plugin to Maven Central and jCenter!

This version brings all the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, plus enhancements to the site plugin. Like other versions before it, this plugin is based on the same version of the Asciidoctor and AsciidoctorJ projects (now using semantic versioning) — 1.5.0.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)
Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)

Installing or upgrading

Installing or upgrading to 1.5.0 is simple. Just update the version in your pom.xml. All necessary dependencies will be pulled in via Maven’s dependency management.

<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.0</version>
  </plugin>
</plugins>

Refer to the example project to copy-paste your way to greatness!

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

Please refer to the manual for the Asciidoctor Maven plugin for information about configuration options and other capabilities of the plugin.

Release highlights

Published the jCenter

The Asciidoctor Maven plugin is now published to Bintray’s jCenter! The means you can find the plugin more easily and its published to the future destination of binaries on the web. You can elect to get notified by Bintray when new versions are available.

Copy non-AsciiDoc files to output directory (#67)

The Asciidoctor Maven plugin now copies non-AsciiDoc files to the output directory so you can put resources, such as images or stylesheets, in the AsciiDoc source folder. This change aligns the behavior of the Asciidoctor Maven plugin with the behavior of Gradle plugin.

Add configuration for setting the gem path and loading additional gems (#109)

You can now specify the location to one or more gem installation directories (i.e., GEM_PATH) using the gemPath configuration option. The main purpose of this setting is to load additional Ruby libraries not packaged in AsciidoctorJ, such as asciidoctor-diagram. You can load additional libraries (absolute path, relative path or gem name) using the require configuration option.

Here’s an example of how to use that configuration within the plugin stanza in your pom.xml:

<configuration>
  <gemPath>${project.build.directory}/gems-provided</gemPath>
  <requires>
    <require>asciidoctor-diagram</require>
  </requires>
</configuration>
You’ll need to use the gem-maven-plugin if you want to download and install gems automatically as part of your build. Refer to the example project to copy-paste your way to greatness!
Configure AsciidoctorJ in isolation (#111)

Prior to 1.5.0, the Maven plugin would allow JRuby to see gems installed external to the project if you had the GEM_HOME or GEM_PATH environment defined (typical if you’re using RVM). This could result in non-reproducible builds.

We’ve gone part of the way of solving this problem by clearing the GEM_PATH environment variable unless it’s specified in the plugin configuration. However, the GEM_HOME environment variable won’t be cleared properly until AsciidoctorJ 1.5.1. In the interim, we issue a warning in the build if GEM_HOME is set to a path outside the build so that you know to reset the value manually (e.g., by running rvm use system).

Properly handle false and empty attribute values (#93)

There was a regression in 0.1.4 that treated both false and empty attribute values as true. Maven needs hand holding to properly convert these values. You can now use an empty string value and it will mean enable the attribute or a false value and it will mean disable the attribute. For example:

<configuration>
  <attributes>
    <toc/>
    <linkcss>false</linkcss>
  </attributes>
</configuration>

This configuration is the equivalent of the following commandline arguments to Asciidoctor:

-a toc -a linkcss!
Generate XHTML in the Maven site plugin (#61)

One of the most important improvements in Asciidoctor 1.5.0 was the addition of the XHTML backend. Simply put, this backend emits XHTML5 (XML-compliant HTML5) instead of the shorthand HTML5 that is the norm. The main reason this backend was added was to fix the behavior of the site module in the Asciidoctor Maven plugin. The XML parser that the Maven site plugin uses will thank you!

EPUB3 output

AsciidoctorJ provides integration with the Asciidoctor EPUB3 converter out of the box. That means you can use it in the Maven plugin without having to declare any additional dependencies. Just set the backend to epub3 and you’re ready to go!

The EPUB3 converter is currently alpha. Expect some glitches while the dust settles!

For more information about issues fixed in this release, please see the 1.5.0 milestone in the issue tracker.

Acknowledgments

Thank you to all the contributors for helping out with this release, and for everyone involved in making Asciidoctor an awesome documentation toolchain and community! We particularly want to that the developers of the Asciidoctor Gradle plugin for giving us lots of ideas for how to make the Maven plugin great!

Enjoy building great documentation!

  • 1 of 1