markdownToHTML() - add flexmark's MacrosExtension as an option

[Baaaaaz]

Identify the Bug or Feature request

closes #5945

Description of the Change

Adds support for:
https://github.com/vsch/flexmark-java/wiki/Extensions#macros
https://github.com/vsch/flexmark-java/wiki/Macros-Extension

Not to be confused of course with MapTool's very own macros and macronames! :)

Possible Drawbacks

None expected.

Documentation Notes

Add MACROS and flexmark's wiki link to the optionalExtension list here: https://wiki.rptools.info/index.php/markdownToHTML

Release Notes

Added optional extension for markdownToHTML() to insert markdown block elements inline

---

This change is 

[bubblobill]

We already have a templating language. I was going to open up handlebars to users which is kinda doubling up.

[bubblobill]

@Baaaaaz Can you have Notes/GMNotes that incorporate the macros? If so, how well do they survive handlebars (which uses flexmark's md to HTML whatsit?

[Baaaaaz]

@bubblobill, this PR is only adding an extension available to the markdownToHtml() MTScript function. I've just amended the PR title to make that clearer! I think Notes/GMNotes and their associated editors on the token properties dialog only uses a limited set of flexmark extensions and this PR is not changing any of those. I suppose anyone can just use the plain old text editor tab rather than html or markdown to store whatever Notes/GMNotes and process it however they want in a MT macro. I suppose the issue comes when rendering that same stuff in stat sheets it will be out of whack?

I suppose if one really wanted, additional flexmark extensions could be added to Notes/GMNotes, whether on by default, or via user preferences. The editor toolbar may need some parity tweaking though, if possible, not sure, not looked, and not planning to look!

For markdown interaction with handlebars, I believe you can combine them and this is a common pattern: handlebars for the dynamic stuff and markdown for the static. Not sure about the effect of specific flexmark extensions, depends if there is any syntax conflict? It may come down sequencing though, processing handlebars first (to create markdown/html syntax) and then process the markdown.

How do you envisage opening handlebars up to users? I see benefit of a function (for use in html5 stuff), but also as new editor options in Notes/GMNotes.

[bubblobill]

#5937 (Currently waiting approval) includes a new helper for parsing md to HTML.

As it's for the function, chances are there won't be any issue .
My only real concern is that any HTML generated will differ between the two.
Will I need to implement the macro stuff into the helper?

[Baaaaaz]

I think your concern is valid if your helper does not handle specific markdown types, markdown extensions, or markdown extension options in the way that markdownToHtml() does, but IMO that goes way beyond just the new flexmark "MACROS" extension added via this PR.

The markdownToHtml() function was introduced in 1.7 so the ability for MT macros to convert markdown to html has already been around for a while. It came with an optional markdown type parameter (defaulting to "GITHUB_DOC") which sets the parser emulation profile and in GITHUB_DOCs case also adds some extensions and sets some extension options. In 1.18 I added another param granting a user the ability to add specific extensions, and this PR just adds one more extension available to users :)

If you are converting markdown to html in your helper function and it does not support any of the markdown types ("GITHUB_DOC", "COMMONMARK", etc) or extensions (Tables, Table of Contents, etc) nor set specific extension options then yes the html output could be different from the two functions. I suppose any unsupported markdown would just remain in the helper function output and users could pass the helper output to a markdownToHtml() function anyway with the desired params... Not ideal though doing half the job in one function.

How is MD_OPTIONS populated in the HandlebarsHelpers MarkdownHelper class?

    private static final MutableDataSet MD_OPTIONS = new MutableDataSet();

markdownToHtml() goes through several steps to create its equivalent to MD_OPTION. Check out that function's java code.
https://github.com/RPTools/maptool/blob/develop/src/main/java/net/rptools/maptool/client/functions/MarkDownFunctions.java

Why does the markdown parser/helper need to be under HandlerbarsHelpers.java anyway? (one java helper to rule them all and in the codebase bind them ;) Could it be removed and users could control the sequenced output of one function into another? Or could you reuse/move what is already in markdownToHtml() to the helper file?

[bubblobill]

Specifically for Stat-Sheets - being the current use for Handlebars - Notes and GM Notes are packaged as either text, markdown, or HTML based on the token settings. The Handlebars helper turns whatever is present into HTML for display.

Currently I expect it only comes in one flavour of markdown, so is not an issue, but if people build their own sheets, and - for example - store token attributes for display in a particular flavour of MD, things could get weird.

Might be safest for me to add specific helpers for different flavours and extensions.
As you say, moving the markdown parser creation bits to a separate class will be the likely result.
I'll save that for after the current PRs get the nod.