asciidoctor-maven-plugin

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

Installation

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>${asciidoctor.version}</version>                   (1)
    ...
  </plugin>
</plugins>
...

1. As this plugin tracks the version of asciidoctor, you can use which every version of asciidoctor you prefer

Usage

Execution setup

...
  <plugin>
    ...
    <executions>
      <execution>
        <id>output-html</id>                                    (1)
        <phase>generate-resources</phase>                       (2)
      </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

Configuration options

Currently there are only three configuration options that the asciidoctor-maven-plugin uses:

• sourceDir — defaults to ${basedir}/src/main/asciidoc

• outputDir — defaults to ${project.build.directory}/generated-docs

• backend — defaults to docbook

More will be added in the future to take advantage of other options and attributes of Asciidoctor. These settings can all be changed in the <configuration> section of the plugin section:

Plugin configuration options

<plugin>
  ...
    </executions>
    <configuration>
      <sourceDir>src/main/doc</sourceDir>
      <outputDir>target/docs</outputDir>
      <backend>html</backend>
    </configuration>
    ...
</plugin>
...