Installing and Using the Asciidoctor Maven Plugin

The Asciidoctor Maven plugin is the official means of using Asciidoctor to render your AsciiDoc documentation using Apache Maven.

Distribution

The Asciidoctor Maven plugin is published to the Maven Central repository. The artifact information is summarized in the table below.

Plugin artifact information
Group Id	Artifact Id	Version	Download
org.asciidoctor	asciidoctor-maven-plugin	1.5.3	pom jar

This plugin depends on the AsciidoctorJ library. If you want to learn more about the library, refer to the AsciidoctorJ manual.

Install or upgrade

As this is a typical Maven plugin, there isn’t much to do to use it, simply add it to your plugins section in your pom:

Plugin declaration

<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version> (1)
  </plugin>
</plugins>

1	This plugin tracks the version of Asciidoctor, so you can use which ever version of Asciidoctor you prefer.

Upgrading the plugin to the next version is simple. Just update the version in your Maven POM. All the necessary dependencies are retrieved from Maven Central the next time you run Maven.

Usage

Execution setup

<plugin>
  ...
  <executions>
    <execution>
      <id>output-html</id> (1)
      <phase>generate-resources</phase> (2)
      <goals>
        <goal>process-asciidoc</goal> (3)
      </goals>
    </execution>
  </executions>
  ...
</plugin>

1	This is simply an unique id for the execution.
2	The Asciidoctor Maven plugin does not run in a specific phase, so one must be specified.
3	The Asciidoctor Maven plugin goal.

Configuration options

There are several configuration options that the Asciidoctor Maven plugin accepts:

sourceDirectory: defaults to ${basedir}/src/main/asciidoc
sourceDocumentName: an override to process a single source file; defaults to all files in ${sourceDirectory}
outputDirectory: defaults to ${project.build.directory}/generated-docs
imagesDir: defaults to images, which will be relative to the directory containing the source files
backend: defaults to docbook
doctype: defaults to article
eruby: defaults to erb, the version used in jruby
headerFooter: defaults to true
compact: defaults to false
templateDir: disabled by default
templateEngine: disabled by default
sourceHighlighter: enables and sets the source highlighter; currently coderay and highlightjs are supported
templateDir: defaults to null
attributes: a Map<String,String> of attributes to pass to Asciidoctor, defaults to null
extensions: a List<String> of non-standard extensions to render; currently .ad, .adoc, and .asciidoc will be rendered by default

Built-in attributes

There are various attributes Asciidoctor recognizes. Below is a list of them and what they do::

title: An override for the title of the document.

This attribute, for backwards compatibility, can still be used in the top level configuration options.

Many other attributes are possible and more will be added in the future to take advantage of other options and attributes of Asciidoctor. Any setting in the attributes section that conflicts with an explicitly named attribute configuration will be overidden by the explicitly named attribute configuration. These settings can be changed in the <configuration> section of the plugin section.

Plugin configuration options

<plugin>
  ...
    </executions>
    <configuration>
      <sourceDirectory>src/main/doc</sourceDirectory>
      <outputDirectory>target/docs</outputDirectory>
      <backend>html</backend>
      <doctype>book</doctype>
      <attributes>
        <stylesheet>my-theme.css</stylesheet>
      </attributes>
    </configuration>
    ...
</plugin>
...

Multiple outputs for the same file

Maven has the ability to execute a Mojo multiple times. Instead of reinventing the wheel inside the Mojo, we’ll push this off to Maven to handle the multiple executions. An example of this setup is below:

Multiple configuration extract

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceHighlighter>coderay</sourceHighlighter>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                </attributes>
            </configuration>
        </execution>
        <execution>
            <id>output-docbook</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>docbook</backend>
                <doctype>book</doctype>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <headerFooter>true</headerFooter>
        <imagesDir>../resources/images</imagesDir> (1)
    </configuration>
</plugin>

1	`imagesDir` should be relative to the source directory. It defaults to `images` but in this example the images used in the docs are also used elsewhere in the project.

Any configuration specified outside the executions section is inherited by each execution. This allows an easier way of defining common configuration options.

Maven site integration

To author your Maven-generated site in AsciiDoc, you must first add a dependency on the Asciidoctor plugin to your maven-site-plugin config:

Maven site integration

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.2</version>
            <dependencies>
                <dependency>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>1.5.3</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

All of your AsciiDoc-based files should be placed in src/site/asciidoc with an extension of .adoc.

For example, the file src/site/asciidoc/usage.adoc will be rendered into target/site/usage.html.

As always, make sure you add a menu item for each page:

<body>
...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
...
</body>

Resources

If you’re interested in modifying or impoving this plugin, checkout the Hacking on the Asciidoctor Maven plugin guide. To file an issue regarding this plugin, visit the plugin’s repository.

Also, don’t forget to join the Asciidoctor discussion list, where you can ask questions and leave comments.