Use adr-tools for AsciiDoc

Use Custom Template for Architecture Decision Records

Posted by Torsten Kleiber on February 15, 2022 Tags: Architecture ADR AsciiDoc Documentation

I looked for a tool to create Architecture Decision Records in AsciiDoc and does not find any. So first I thought, I would have to (re)implement one. But look, how easy it really was.

I saw this Issue for adr-tools, which describes how to use a custom template.

Usually adr-tools create Markdown format, but my idea was to write an Asciidoc template instead.

So first you have to install adr-tools. I use the variant "Git for Windows: git bash".

In the target directory of the adr-tools do the following:

  1. rename both *.md files to *.adoc

  2. change the content of these both files to AsciiDoc, which simple means replace all occurrences of "#" with "="

  3. change other content according to your needs

  4. replace all occurrences of ".md" with ".adoc"

Then you can test this:

$ adr init doc/adr
doc/adr/0001-record-architecture-decisions.adoc

$ adr new Change File Format of Architecture Decision Records to AsciiDoc
doc/adr/0002-change-file-format-of-architecture-decision-records-to-asciidoc.adoc

$ cat doc/adr/0002-change-file-format-of-architecture-decision-records-to-asciidoc.adoc
= 2. Change File Format of Architecture Decision Records to AsciiDoc

Date: 2022-02-15

== Status

Accepted

== Context

The issue motivating this decision, and any context that influences or constrains the decision.

== Decision

The change that were proposing or have agreed to implement.

== Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.

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

That’s it!