Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Configuring the AsciiDoctor Maven Plugin

DZone's Guide to

Configuring the AsciiDoctor Maven Plugin

AsciiDoctor is a handy documentation tool. In this post, we take a look at how to integrate it easily with Java using Maven.

· Java Zone
Free Resource

Download Microservices for Java Developers: A hands-on introduction to frameworks and containers. Brought to you in partnership with Red Hat.

AsciiDoc is a great way to write technical documentation. It is text based, can be committed and versioned in your VSC with your project, has a rich syntax, has a huge ecosystem, integrates with several tools (such as PlantUML that I love), and, if there is still something missing, you can use extensions or create your own. And if you use the asciidoctor-maven-plugin to automatically generate all your documentation, you end up customizing it.

In this post, I explain a few configurations that I use in the asciidoctor-maven-plugin.

Including Remote Code in Your Documentation

If, like me, you code and write documentation about your code with AsciiDoctor, you might use the source code block with syntax highlighting. So, you copy/paste your code into an Asciidoc [ source ] block and you can even give it a code highlighter (here, coderay), a language (Java), a title, and so on. Then, you realize that you don’t want to copy/paste code, you just want to point at the code itself. So, if the Java file Book.java is sitting on your drive, you use the include:: directive and pass it the relative or absolute path. If you don’t want to include all the file, you can add just a portion of it, by using tags (eg. here the tag is called snipped).

== Using include with a local file

[ source ]
----
include::/Users/agoncal/Code/src/main/java/Book.java[tag=snippets]
----


This is much better than copy/paste as you can change your code and it will get updated in your documentation once you re-generate it. Then, you realize that you don’t want to point to a file on your disk, but on a remote file on GitHub. Asciidoctor allows you to put a URI in the include directive:

== Using include with a remote file

[ source ]
----
include::https://raw.githubusercontent.com/agoncal/agoncal-book-javaee7/master/src/main/java/org/agoncal/Book.java[tag=snippets]
----


This will not work because you need to allow Asciidoctor to access remote URIs by passing the <allow-uri-read/> attribute. For security reasonsm you can’t just add this attribute to the document itself (with a : :allow-uri-read:), but instead, pass it on the pom.xml:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <configuration>
        <attributes>
            <allow-uri-read/>
        </attributes>
    </configuration>


If, like me, you use PlantUML, you either have the choice to create your diagrams in separate .puml files and include them in your document or embed them straight into your .adoc file. Asciidoctor has a nice integration with PlantUML. You can add a diagram straight into the document:

== PlantUML Diagram

[plantuml,auth-protocol]
....
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
....


For that to work, you need to setup the asciidoctor-diagram dependencies:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <version>${asciidoctorj.diagram.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <attributes>
            <data-uri/>
        </attributes>
        <requires>
            <require>asciidoctor-diagram</require>
        </requires>
    </configuration>


Notice the data-uri attribute. You can either set it on the pom.xml or straight into the document itself with :data-uri:. This allows you to embed the image straight into the HTML itself using the <img src="data:image/png;base64> syntax.

Using Extensions

If you think that Asciidoctor is only great, it’s because you don’t know extensions! With extensions, the sky is the limit to Asciidoctor. There are a few official and third party extensions, you can build your own using an API, and you can play with the nice Asciidoctor Extensions Lab. The catalog of this lab extension is quite large and you can easily use the ones you want.

Let’s say I want to use emojicons in my document and also refer to Gists, I have two extensions that I can use: the Emoji Inline Extension and the Gist Block Macro.

== Emoji Inline Extension (emoji-inline-macro.rb)

I trully emoji:heart[lg] my little green emoji:turtle[1x]!

== Gist Block Extension (gist-block-macro.rb)

.A Gist from Dan Allen
gist::mojavelinux/5546622[]


But before using these extensions, you need to copy the Ruby files (here, under ${project.basedir}/src/main/asciidoc-extensions) and configure them in the pom.xml as follow (notice the allow-uri-read attribute to allow reading from external URIs for Gist in this example):

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <configuration>
        <attributes>
            <allow-uri-read/>
        </attributes>
        <requires>
            <require>${project.basedir}/src/main/asciidoc-extensions/emoji-inline-macro.rb</require>
            <require>${project.basedir}/src/main/asciidoc-extensions/gist-block-macro.rb</require>
        </requires>
    </configuration>


When you use extensions, sometimes you hit an error because a Gem is not installed. For example, if you need a Lorem Ipsum in your document, there is an extension for generating it: lorem-block-macro. But if you use it as explained above, you will get an exception because this extension needs the Middleman Gem. You can install this Gem in different ways… or leave your good old Maven to do it.

The Middleman Gem is published in the rubygems.org repository. And the RubyGem repository is proxied by TorqueBox at http://rubygems-proxy.torquebox.org. So it’s just a matter of adding this repository in your pom.xml and getting MiddleMan through Maven coordinates and the <type>gem</type>:

<dependencies>
    <dependency>
        <groupId>rubygems</groupId>
        <artifactId>middleman</artifactId>
        <version>4.2.1</version>
        <type>gem</type>
    </dependency>
</dependencies>
<repositories>
    <repository>
        <id>rubygems-proxy</id>
        <name>Rubygems Proxy</name>
        <url>http://rubygems-proxy.torquebox.org/releases</url>
        <layout>default</layout>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
            <updatePolicy>never</updatePolicy>
        </snapshots>
    </repository>
</repositories>


We got the Gem into our Maven repository, but now we need to install it. For that, we use the Maven Gem plugin and set it up on the Maven initialize phase. A simple mvn initialize will install all the needed Gems for Middleman in your target/rubygems directory:

<plugin>
    <groupId>de.saumya.mojo</groupId>
    <artifactId>gem-maven-plugin</artifactId>
    <version>${version.gem.maven.plugin}</version>
    <configuration>
        <skip>true</skip>
        <jrubyVersion>${version.jruby}</jrubyVersion>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>initialize</goal>
            </goals>
        </execution>
    </executions>
</plugin>


Then, it’s just a matter of using the Lorempsum extension straight into your document:

== Lorem Extension (lorem-block-macro.rb)

lorem::sentences[5]

Conclusion

Because I am mostly Maven centric, I like to automatically generate documentation from Maven, so I use extensively the asciidoctor-maven-plugin. But I have to say, sometimes I get lost in the documentation to find what I need. The Asciidoctor examples don’t always give the Maven configuration, so you have to spend some time trying around (check the asciidoctor-maven-examples).

Look at the entire code of my samples above, and if you have any other tips or suggestions on how to configure the asciidoctor-maven-plugin, don’t hesitate to leave a comment, create an issue, or push a PR.

Download Building Reactive Microservices in Java: Asynchronous and Event-Based Application Design. Brought to you in partnership with Red Hat

Topics:
maven ,java ,asciidoctor ,ruby gem ,tutorial

Published at DZone with permission of Antonio Goncalves, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}