Mermaid support

[kovergard]

It would be great if support for Mermaid charts could be added. That would allow us to keep documentation in repo, but distribute to less technical persons as PDF. :-)

[PeterWone]

Historically Print uses the same rendering pipeline as the built-in Markdown preview so as to get the benefits of any Markdown extensions that may be installed. There is, as you probably know, a Mermaid Markdown extension for VS Code that works with the built-in Markdown preview.

It doesn't work with Print because it depends on script running in the browser, and the way the script is handled in the built-in Markdown rendering pipeline is not compatible with Print.

Recently I have been working on a document rendering extension for Print that uses a library called pagedjs to string a bunch of Markdown documents together as chapters of a book. It has fundamentally the same problem. To deal with it I built my own Markdown rendering pipeline and handled scripts myself.

If I were to rewrite the Print Markdown rendering pipeline to behave the same way, it would be possible to support pipeline extensions that run script in the browser, such as Mermaid. However, to meet not unreasonable user expectations I'd have to figure out what Markdown extensions are installed and do some jiggery pokery to get the same functionality into my own pipeline.

It's a reasonable request, and I know how to do it, but it's a lot more work than one might think.

Of course, if someone got keen and put together a PR, this would be very warmly received. Technical assistance would definitely be available for such brave souls. If someone were to take this on, Markdown rendering could be broken out into a separate extension that overrides the one baked into Print, allowing experimental deployment and taking the pressure off by having its own release cycle. When it reached maturity, baked in support could be dropped and an extension dependency declared.

[kovergard]

Thank you very much for the detailed reply, Peter.

I had imagined it possible to piggyback on the existing preview rendering, but if you have to implement your own rendering engine for mermaid, I certainly see the challenge.

Keep up the good work, the Print extension already works wonders. :-)

[PeterWone]

Not only is the rendering pipeline implemented (see below) it handles !include filename.ext directives allowing you to have a file per class like in source code. Includes are resolved recursively, and cycles are handled so you can define each entity and then define groups of them for parts of a system and combine those parts into ever more complete diagrams.

Documents rendering a lot of diagrams got a bit slow, so we took a leaf out of git's book and used SHA256 hashes to fingerprint diagrams for persistent caching like browser. Once a diagram has been rendered, it will be loaded from cache unless you change the source. Because fingerprinting happens after includes are resolved, change detection works all the way down. If you thought of it as an incremental compiler for documents, you wouldn't be wrong.

[PeterWone]

OK brand new rendering pipeline with support for Mermaid among many other diagramming notations. Here's what is currently supported.

BlockDiag	BPMN	Bytefield	SeqDiag	ActDiag	NwDiag
PacketDiag	RackDiag	C4 with PlantUML	D2	DBML	Ditaa
Erd	Excalidraw	GraphViz	KaTeX	Mermaid	MHCHEM
Nomnoml	Pikchr	PlantUML	SmilesDrawer	Structurizr	Svgbob
Symbolator	Tikz	UMLet	Vega	Vega-lite	WaveDrom
WireViz