Include more flexmark extensions for improved markdown to html rendering

[UBessle]

we would like to move our architecture documentation from Confluence pages to structurizr models, and markdown files using your excellent tool structurizr-site-generatr.

Unfortunately currently we miss some possibilities to achieve this goal in a satisfactory way. The main drawback is, that confluence provides much more formatting possibilities, than the basic markdown support from flexmark inside of structurizr-site-generatr.

We've looked into flexmark and it looks, as nearly everything would be possible with flexmark as well, if we could use some of the numerous existing flexmark extensions. But currently structurizr-site-generatr is restricted to be using tables extension only.

// MarkdownToHtml.kt
options.set(Parser.EXTENSIONS, listOf(TablesExtension.create()))

It would be great, if we could use at least the following extension additionally

• AnchorLink
• Emoji
• Gfm-TaskList
• GitLab Flavoured Markdown
• Table-of-Contents-Extension

It would be even better, if we could somehow control, which extensions are used and which options are set. Than we could later on decide, to use additional extensions as well, like

• admonition
• Autolink
• Gfm-Users
• Footnotes
• ...

[dirkgroot]

@UBessle thanks for the issue! Looking at the functionalities of the available Flexmark plugins, I really like this idea!

We'll have to think about how to make adding and configuring Flexmark plugins dynamic, as opposed to hardcoded. Ideally, I would like this to be configurable using a properties block in the Structurizr DSL model at workspace level. Something like:

workspace {
  properties {
    "flexmark.plugins" "AnchorLink,Emoji"
    "flexmark.Emoji.USE_IMAGE_TYPE" "UNICODE_ONLY"
  }
}

I'm not sure how hard or easy it would be to implement this. Any ideas?

[UBessle]

I'm totally with you, that adding and configuring Flexmark plugins should be dynamically if somehow possible. But i would advise against the idea, to include the neccessary configuration info in the structurizr DSL workspace.
The configuration does not describe the architecture of my system, so it does not belong to the workspace. It is rather a configuration of the tooling i'm using to generate the architecture documentation web site.

I would prefer having a commandline parameter
--config "flexmark.extensions=AnchorLink,Emoji; flexmark.Emoji.USE_IMAGE_TYPE=UNICODE_ONLY"

Alternatively / additionally a commandline parameter could point to a configuration file
--config-file site-generator.properties

site-generator.properties

flexmark.plugins = AnchorLink,Emoji
flexmark.Emoji.USE_IMAGE_TYPE = UNICODE_ONLY

I'm not sure if i woul prefer having the simple properties file format or support for json / yaml files

[dirkgroot]

Maybe you're right. The reason for my idea of using workspace-level properties is that Simon Brown also uses properties on the workspace, views and model elements to customize the generation of diagrams. See https://github.com/structurizr/export/tree/main/src/main/java/com/structurizr/export/plantuml.

However, I'm not sure if I like that approach. I think that a separate configuration file may indeed be a better approach, also because I think that JSON or YAML may be better suitable for this kind of configuration.

[UBessle]

May we help you somehow in producing this improvement?

[dirkgroot]

Sure! Feel free to create a pull request if you have a good idea for implementing this feature.

[UBessle]

I'm not an experienced Kotlin developer. Could you please provide a small section in the README.md how to participate in development?

• how to build locally
• how to run tests locally
• how to run locally built versions
• how to document changes / provide updated documentation
  This would help me (and perhaps others as well) to come up to speed in short time

[simonbrowndotje]

The reason for my idea of using workspace-level properties is that Simon Brown also uses properties on the workspace, views and model elements to customize the generation of diagrams. ... However, I'm not sure if I like that approach.

Yup, I've learnt (the hard way) that many people using the Structurizr toolset are "architects" rather than developers, some with a very limited technical background. It's for this reason I tend to err on the side of opinionated simplicity. 😂

[dirkgroot]

But architects ARE developers... right...? 😉

But I understand your choice. Architects come in many shapes and forms and have very different backgrounds. Creating something like this for such a diverse group of users is hard.

For this tool, I think we should lean towards sensible defaults resulting in something that's usable for lots of people "out of the box", and some optional configurability for "advanced" users.

[dirkgroot]

@UBessle That's a good idea. I'm a bit busy lately, but I'll try to add a CONTRIBUTING.md somewhere in the upcoming week.

[dirkgroot]

@UBessle I've added CONTRIBUTING.md, with some basic information on working with the source code. Is this sufficient for you to get started?

[UBessle]

Thanks for the CONTRIBUTING description. I was absent last week. Hopefully i can start working on the PR next week.

[jp7677]

I've finally took some time to document the structurzr properties that affect the look and feel of the generated web site, see #206. In my opinion, any configuration switches we add for markdown rendering would be in the same league as those and thus should be properties in the view section of the C4 DSL (applied it looks like https://github.com/avisi-cloud/structurizr-site-generatr/blob/main/docs/example/workspace.dsl#L159).

[simonbrowndotje]

Just my 2c ... I can see properties named structurizr.style.* confusing people. Why not name them something like generatr.style.* to make it explicit these are Site Generatr specific properties?

[jp7677]

Just my 2c ... I can see properties named structurizr.style.* confusing people. Why not name them something like generatr.style.* to make it explicit these are Site Generatr specific properties?

Yeah, I agree. site-generatr.style.*, site-generatr.search.* (and may be site-generatr.markdown.* in the future) might even be better.
Well, naming is hard :)

[jp7677]

Just my 2c ... I can see properties named structurizr.style.* confusing people. Why not name them something like generatr.style.* to make it explicit these are Site Generatr specific properties?

Already proposed as part of #206

[dirkgroot]

Thanks for your feedback, @simonbrowndotje! I completely agree that using the stucturizr prefix could lead to confusion.

[dirkgroot]

I'm closing this issue, as the requested feature is now built and merged to main.