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.

<project>
    ...
    <build>
        ...
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>3.1.1</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>
  ...
</project>

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.