Introduction

The Asciidoctor Maven Plugin is used to convert AsciiDoc documents using Asciidoctor. The plugin offers a comprehensive way to configure a conversion process using Asciidoctorj in a declarative way.

Goals overview

The plugin has 3 goals. None of these are bound to any specific phase.

asciidoctor:process-asciidoc: main goal of the plugin, it is used to convert documents during a normal Maven build.
asciidoctor:auto-refresh: used to support writing documents. This goal will run until stopped and will convert documents online when they are modified.
asciidoctor:http: used to support writing HTML documents. On top of converting documents online when they are modified, it will push them to a local HTTP server.

Usage

Specific instructions can be found in the specific usage page of each goal.

Here is a simple example of an HTML conversion.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.1.0</version>
    <executions>
        <execution>
            <id>convert-to-html</id>
            <phase>generate-resources</phase> (1)
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.directory}/html</outputDirectory> (2)
                <attributes> (3)
                    <source-highlighter>coderay</source-highlighter>
                    <imagesdir>./images</imagesdir>
                    <toc>left</toc>
                    <icons>font</icons>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

1	Asciidoctor maven plugin’s phase and goal must be set explicitly in an execution block.
2	Asciidoctor options can be set in the `<configuration>` section. Note the backend is `html5` by default.
3	Asciidoctor attributes can be set inside the `<attributes>` section. These are unrestricted key value pairs, with a special case for boolean values.