Introducing the Asciidoctor Maven plugin

by Jason Porter -

I’d like to introduce you to the easiest way to use AsciiDoc from Maven, the Asciidoctor Maven plugin!

Plugin artifact information
Group ID Artifact ID Latest version Download




pom jar

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:

pom.xml fragment: Asciidoctor Maven plugin configuration

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.


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


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.


We’re always open for patches, better documentation, feature requests, evangelizing or any help you’re able to provide.