AsciiDoctor, Maven and IntelliJ
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