Use AsciiDoc Templates for your Architecture Decisions with Java Based ADR-J Tool

Create AsciiDoc Templates for ADR's and use them in your Project on all Platforms

Posted by Torsten Kleiber on March 31, 2022 Tags: Architecture ADR AsciiDoc Documentation

In my blog Use adr-tools for AsciiDoc I have described, how to change the tool to write my Architecture Decision Records in AsciiDoc. But there are a lot of drawbacks with this approach, e.g. some of the features like linking and superceding decisions does not work. ADR Tool is based on shell scripts, so you have to provide and know a *nix emulation on windows. In the meantime I found Java base ADR-J Tool and will show you here if this works better for my purposes.

According to its own architecture decision records it support only markdown as ADR-Tool does. And again I found nothing clear here in the documentation about AsciiDoc too.

But similar as in ADR-tools I found here the closed Issue Extend to use Asciidoc as well as markdown and the related pull request describes, what I have to prepare one time on my Windows 11 machine:

  1. First I clone the repository https://github.com/adoble/adr-j.

  2. Then I build and install the tool as decribed in INSTALL.md

  3. When testing the tool I get following error:

    C:>adr
Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError: org/doble/adr/ADR has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

  4. As I have installed Oracle JRE 8 on my Windows 11 machine I have to change these both parameters to 8

    build.gradle
    Unresolved directive in <stdin> - include::https://raw.githubusercontent.com/adoble/adr-j/main/build.gradle[lines=19..20]

  5. After building again now my fist call works.

  6. Next step is to create asciidoc templates.

    1. As I want to use MADR format for Architecture Decision Records too I copy the markdown templates files madr.md and madr_initial.md from the project now with the extension .adoc.

    2. Then I convert all the Markdown specific syntax to AsciiDoc syntax.

    3. If you use IntelliJ IDEA with the AsciiDoc plugin you can do both steps in one go via right click on the file and choose Convert to AsciiDoc. This is how it looks like:

      adr j tool with madr template for asciidoc template

I would recommend to copy the AsciiDoc templates to your project first. Then you can test this:

C:>adr init -i <path>\madr_initial.adoc -t <path>\madr.adoc
Creating ADR directory at <path>\doc\adr

C:>more doc\adr\0001-record-architecture-decisions.adoc
= Record Architecture Decisions
...

C:>adr new Save ADR Templates for Projects
Creating ADR
Created ADR at C:\Users\torst\doc\adr\0002-save-adr-templates-in-projects.adoc
Opening Editor on C:\Users\torst\doc\adr\0002-save-adr-templates-in-projects.adoc ...
C:\Users\torst\doc\adr\0002-save-adr-templates-in-projects.adoc

C:\Users\torst>more doc\adr\0002-save-adr-templates-in-projects.adoc
= Save ADR Templates in Projects

* Status: Proposed
...

After that you have to fill the new file with relevant content for your Architecture Decision.

adr j tool with madr template for asciidoc generated

If you try to work with links in ADR via adr new -link you will see, that at the moment the file reference will not be created at the moment. Similar happens, when you try to use adr edit 1 to open ADR 1 in your configured editor. This is related to some existing hard references to Markdown '.md extension in the code. I have created a pull request, which should solve this.

You find the change already in my fork on GitHub.

That’s it!