adr-tools icon indicating copy to clipboard operation
adr-tools copied to clipboard

Published 20 hours ago • verified publisher icon npryce

Asciidoc Support

Open mikeholler opened this issue 5 years ago • 7 comments

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?

mikeholler avatar Oct 15 '18 21:10 mikeholler

What do you mean by “arbitrary extensions”?

npryce avatar Oct 25 '18 19:10 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 avatar Nov 05 '18 12:11 npryce

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

npryce avatar Nov 05 '18 13:11 npryce

@mikeholler did you finally make adaptations to support asciidoc?

stephlag avatar Jan 17 '19 09:01 stephlag

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.

mikeholler avatar Jan 24 '19 14:01 mikeholler

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.

sdavids avatar Nov 08 '19 11:11 sdavids

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?

rlemaitre avatar May 25 '20 20:05 rlemaitre