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)
        <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 (only for the moment) asciidoctor maven plugin goal

Configuration options

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

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

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

• backend — defaults to docbook

• doctype — defaults to article

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>
      <sourceDirectory>src/main/doc</sourceDirectory>
      <outputDirectory>target/docs</outputDirectory>
      <backend>html</backend>
      <doctype>book</doctype>
    </configuration>
    ...
</plugin>
...

Hacking

Developer setup for hacking on this project isn’t very difficult. The requirements are very small:

• Java

• Maven 3

• Ruby (1.9.x)

• Bundler

Everything else will be brought in by either Maven or Bundler.

Updating the gems in the project

All of the gems for the project must be self contained so they’re included in the final jar. To update the gems in the project, simply issue:

bundle install --path src/main/resources --standalone --clean

from the project root. This will retrieve any new versions since the last install, or Gemfile change, install them into the correct location and clean any unused versions.

Testing

http://spockframework.org/(Spock) is used for testing the calling of the jRuby code from the Mojo. This will be downloaded by Maven. Tests are run simply by:

mvn clean test

Or any of the other goals which run tests. If I can figure out a good way to setup a ruby testing environment I’ll do that as well, but none exists at this time.