Introducing the Asciidoctor Maven plugin
by -
I’d like to introduce you to the easiest way to use AsciiDoc from Maven, the Asciidoctor Maven plugin!
| Group ID | Artifact ID | Latest version | Download |
|---|---|---|---|
org.asciidoctor |
This plugin is a great option for projects interested in using AsciiDoc to author documentation, or any part of this project utilizing AsciiDoc. Best of all, it’s already available from Maven Central.
How it works
The Maven plugin loads JRuby, scans for AsciiDoc files in the specified directory, then invokes Asciidoctor to render them. You have the option of rendering the files to HTML 5 and DocBook 4.5.
Setup and usage
Adding this plugin to your Maven POM is simple. Just add this plugin declaration:
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>0.1.1</version>
<executions>
<execution>
<id>render-asciidoc</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
<configuration>
<sourceDirectory>docs</sourceDirectory>
<outputDirectory>target/docbook/en-US</outputDirectory>
<backend>docbook</backend>
</configuration>
</plugin>Execution is handled by Maven when you execute a build.
You can find more detailed information about setup and usage in the README located in the project’s repository on GitHub.
Versioning
The version of the Maven plugin will track the version of Asciidoctor. In most cases, the version number will match the Asciidoctor version (e.g., 0.1.1). If an interim fix needs to be made to the plugin, an additional number will be added to the end of the Asciidoctor version number (e.g., 0.1.1.1).
Future
Currently, the plugin uses its own JRuby integration to invoke Asciidoctor (which is written in Ruby). The next version (roadmap) will use the newly-released Asciidoctor Java integration to streamline the hand off and simplify maintenance of the project.
In conjunction with the change to use the Asciidoctor Java integration internally, new configuration options will be added. One of those options will allow you to pass AsciiDoc attributes to the renderer. AsciiDoc attributes control options such as adding a table of contents, turning on section numbering and configuring the source highlighter.