Introduction

In the previous blog entry about AsciiDoctor, I recommended saving the generation command into a shell script or batch file to make it easy to add additional processing/pre-processing later.

While at the time this seemed very straightforward, for those of us who want to generate documentation as part of a Java build, there’s a more convenient approach. There is a Maven plugin for AsciiDoctor (Maven appears to have plugins for just about everything), making it easy to generate documentation from templates as part of a Maven build. This in turn can be used in conjunction with other functionality provided by Maven (e.g. Maven resources plugin to move custom css into an appropriate location ready for upload to a website) to make a more complete build script.

The Asciidoctor Maven Plugin

The Asciidoctor Maven Plugin can be added to the plugins section of a maven build script (pom) to convert asciidoc files into html (or other output formats). The basics of this are relatively straightforward, simply define an execution (or multiple executions) which output to desired locations.

The plugin is highly configurable but by default will use src/main/asciidoc as its input directory for asciidoc files, we chose to use this, and also to use the default output directory target/generated-docs. We treat the generated html as generated resources on which we might want to perform further processing, so we chose the generate-resources phase for our processing. Our plugin snippet (at time of writing) is as below:-

pom.xml snippet
----
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.3</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <sourceHighlighter>coderay</sourceHighlighter> (1)
                <attributes>
                    <linkcss>true</linkcss> (2)
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>
----
<1> Use coderay source highlighter to provide source code highlighting (e.g. the above snippet)
<2> Link to an external css file rather than embedding style information in the generated html

As can be seen, the defaults (at least for our purposes) seem pretty reasonable, and all we had to specify was the backend (we want to output html 5) and the fact that we want to link, rather than embed, our styles (linkcss). We still need to set up the packaging ready for automated upload to our blog using the maven resources plugin, and then configure automated upload on approval of blog changes, but this is a pretty convenient start.