Always generate markdown in addition of plain text documentation and let user choose which one to show through a toggle box in the report.

[jbsarrodie]

See:

• https://marked.js.org for markdown conversion to html
• https://css-tricks.com/the-checkbox-hack/#article-header-id-4 for the toggle in CSS.

[jbsarrodie]

I've implemented a first support for markdown in the markdown branch. I've used marked.js which is really easy to use and very good (it supports several markdown flavours and I decided to use GFM).

Instead of simply rendering documentation through marked.js, I first escape it so content which lokks like html tag is not interpreted. I did this choice because It seems to me very unlikely that someone uses HTML markup in Archi other than for really showing some example of html (and not to have it interpreted in some ways). I also configured marked.js to render newline as <br> tags, which also make sens IMHO.

I tested it with my own models and result is really good 99% of the time. So this is going to become the default but of course should be an option.

I see two ways to make it an option:

• Option at generation time
• Option in the report itself

I prefer the second way of doing it because it is very likely that it will works for 99% of views, but only for some of them people will want to see the original text. In this case, it would be bad to normal documentation for all the other views.

My feeling is that we should have this behaviour and options:

• Generated report includes both version and has a way to select which one to show. Default version is markdown, unless some model level property is set (Report:Model:DefaultsToMarkdow = false), but if set, user will anyway be able to switch markdown on.
• If a view's documentation should be forced to text or markdown, then a property can be set (Report:View:RenderDocumentationAs = text|markdown). In this case, only the choosen option will be visible in the report, for this specific view.

[Phillipus]

Option in the report itself

I prefer this one too.

Will test...

[jbsarrodie]

Done in markdown branch. I let people test during some days before making it "official".

[Phillipus]

Nice work. I'll do more testing... :-)

[jbsarrodie]

The good thing is that I've added a "preferences" dialog so I can use it for other purposes if needed.

BTW, I'm using some part of https://picnicss.com. This is a simple, yes powerful, CSS library using only CSS. I use it for tables and model dialog.

[Phillipus]

I did some basic MD testing, and it works well. :-) I like the way that changing the MD preference updates in real time.

Now that we can set the text control font for the Documentation field in Archi to a fixed-width font it makes creating MD tables possible. ;-)

[jbsarrodie]

Thank you for testing.

I've published a new release.

[Phillipus]

I've published a new release.

Got it. Works well. :-)