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