Usage

How to convert AsciiDoc documents

These are the minimal steps to convert your AsciiDoc documents to HTML with the asciidoctor-maven-plugin.

  1. Place your AsciiDoc sources in src/docs/asciidoc.

  2. Add the minimal configuration to your pom.xml.

    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>${asciidoctor.maven.plugin.version}</version>
        <executions>
            <execution>
                <id>asciidoc-to-html</id>
                <phase>generate-resources</phase>
                <goals>
                    <goal>process-asciidoc</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
  3. Run the plugin’s associated phase.

    $ mvn generate-resources

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>2.2.6</version>
    <executions>
        <execution> (1)
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html</backend>
                <attributes>
                    <toc/>
                    <linkcss>false</linkcss>
                    <source-highlighter>coderay</source-highlighter>
                </attributes>
            </configuration>
        </execution>
        <execution> (2)
            <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>  (3)
        <sourceDirectory>src/main/asciidoc</sourceDirectory>
        <headerFooter>true</headerFooter>
    </configuration>
</plugin>
1 First execution, converts documents to HTML.
2 Second execution, converts documents to DocBook.
3 Any configuration outside the executions section is inherited by each execution. This allows an easier way to share common configuration options.