Asciidoc Support

[mikeholler]

Hi there,

I love this project and want to use it internally. We like to use adoc (asciidoctor) and judging from some time I spent reading the source code it seems pretty simple to support an alternative format. Would you be interested in accepting a PR that adds support for arbitrary extensions, so we (and others) can use the markup language we feel comfortable with?

[npryce]

What do you mean by “arbitrary extensions”?

[npryce]

There are several complicating factors to consider..

1. The tool (loosely) parses the Markdown documents to extract links and statuses. How can that be done in a way that supports Markdown and Asciidoc (and others, because if you add Asciidoc someone will request another format before long) without peppering the source with conditional statements?
2. How can an additional format be supported without doubling the number of tests required? (Maybe working that out will also address point 1)
3. Other tools also parse ADRs in the format managed by adr-tools -- Documentation pipelines, architecture visualisation tools, etc. How will the format be signalled to other tools so that they know how to parse ADRs correctly?

[npryce]

One thing you could do is convert the ADR Markdown to Asciidoc with Pandoc and feed it into your Asciidoc-based publishing pipeline.

[stephlag]

@mikeholler did you finally make adaptations to support asciidoc?

[mikeholler]

Hey @stephlag, my coworkers and I decided that it's not a bit deal if we maintain ADRs in markdown and our other architectural docs in asciidoc, since they're all converted to HTML for viewing. I think support for different formats would still be a good goal for this project, but I don't have enough stake in the game to help make it happen.

[sdavids]

One major advantage of asciidoc is the possibility to include embedded diagrams via plantuml for example.

Markdown > Pandoc > Asciidoctor is of no help in that case.

[rlemaitre]

Hey all,

I've made a PR to allow using AsciiDoc instead of Markdown (#101). Unfortunately, the CI fails on MacOS due to a weird shell_session_update message in the output.

I've taken the option to have the language specified at ADR log initialisation.

Can you tell me what you think about it?