Support Markdown in Documentation/Purpose field

[Phillipus]

I'm opening this as a new issue so we can start with a clean discussion, as the other ones are a bit out of date.

#34
#293

[Phillipus]

The feature request is to support the rendering of MD in the Documentation/Purpose field.

Where should the MD be rendered?

• HTML Report
• Jasper Report

Where should the MD not be rendered?

• In Archi itself

What Java library to use?

• See https://github.com/commonmark/commonmark-java
• Maven jar - https://mvnrepository.com/artifact/org.commonmark/commonmark/0.21.0

Example code:

Parser parser = Parser.builder().build();
Node document = parser.parse("This is *Markdown*");
HtmlRenderer renderer = HtmlRenderer.builder().build();
String text = renderer.render(document);  // "<p>This is <em>Markdown</em></p>\n"

[Phillipus]

The Documentation text has to be converted to HTML from MD before exporting to the reports.

• When is the conversion done?
• Is it optional?
• How do we know that the field contains MD or plain text?

The HTML report renders documentation text using StringTemplate like this:

<div class="convertlinks documentation" style="white-space:pre-wrap">^element.Documentation;format="xml-encode"^^element.Purpose;format="xml-encode"^^element.Content;format="xml-encode"^</div>

In order to render HTML the format="xml-encode" part would have to be removed.

• How to make this conditional?
• How do we know if the Documentation contains MD or plain text?

Similar questions for Jasper Reports:

• See [Feature Request] Support of MarkDown in documentation area #293 (comment)
• Add markup="html" to the styles in style.jrtx file
• How do we know when to use that style? Plain text should not have markup="html"

[Phillipus]

In summary, it's easy enough to add a Java library to convert MD to HTML, the problems are when to do that rendering and how to handle escaped or unescaped HTML in the reports. And to know when text is MD and when it is plain text. Until that is solved, we can't implement it.

[Phillipus]

I created a POC implementation here

The main problems are:

• The rendering in the HTML report looks bad because it uses the host report's style-sheet. It needs to have its own style-sheet.
• Very limited support of rendering HTML in Jasper Reports. It's so limited that it's useless.

From my tests, I'd say that it's a non-starter for the Jasper report and only possible in the HTML report if we can figure out how to attach a separate style-sheet to the resulting documentation HTML.

Another thing is label expressions. Let's suppose you have markdown in your documentation field and you use a label expression ${documentation}. Then you will not see the rendered markdown in the diagram because it cannot render it there.

So, the main issue here is not how to convert MD to HTML but how well HTML is rendered in the target. In our case we have two targets, HTML and Jasper reports, and HTML does not render well.

It might be better to apply a JavaScript MD renderer to the HTML report as was suggested here.