AsciiDoctor, Maven and IntelliJ

Christoph Kappel · · , , , · Reading time 2 minutes
In this article

AsciiDoc is one of my favorite text processors for anything related to Documentation-as-Code.

I use it quite excessively in my current project, for documentation on service level but also for architecture documentation based on ARC42.

If you really want to look into it I suggest to have a look at the documentation Asciidoc Writer’s Guide.

It is as convenient as Markdown and has a few other tricks up its sleeve like support for images and a proper way to use a hierarchy of documents. The only thing that kind of annoys me is the import idiocy - a few of you probably know from PHP:

If you include something from a subdirectory, all other other includes are relative to this new root now. This leads to interesting issues, especially if you want to deal with images.

Images &

One of the few things that you commonly see is basically to prefix every image include with the :imagedir: attribute:

:imagedir: ./images
image::foobar.png[caption=Test]

This leads to lots of redundancy and makes a change of this quite nasty, once you are dealing with a large document.

Maven &

When you are using maven, there is another way just to set the imagedir attribute inside of your pom:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>

    <configuration>
        <attributes>
            <imagesdir>./images</imagesdir>
        </attributes>
    </configuration>
</plugin>

IntelliJ &

There seems to be some kind of unwritten rule, that IntelliJ always has to fail for something that works quite nicely with maven even when you install the asciidoc plugin - so no surprises here.

After some digging around, I discovered this config file:

The plugin supports the usage of a config file, that can be placed in the root level of your document and gets prefixed automatically to every AsciiDoc file that is below this paths:

:icons: font
:imagesdir: {asciidoctorconfigdir}/images