Support some diagram language (written inline or in dedicated files)

[kwin]

Is your feature request related to a problem? Please describe. Please support generating diagrams out of some diagram language like mermaid, PlantUML. Those could either be written inline or just referenced from markdown. That should lead to generating the SVG during build and afterwards generate HTML with an image tag referencing the generated SVG.

Describe the solution you'd like Something similar to https://github.com/danielyaa5/puml-for-markdown but working in Java (locally)

Describe alternatives you've considered The current solutions usually require NodeJS or another native binary (and are therefore not cross-platform)

[ghost]

Mermaid does not produce SVG files that conform to the SVG specification, which means that they do not render outside of a web browser environment. This is a known issue. EchoSVG has taken some strides to handle rasterizing Mermaid's non-compliant output.

KeenWrite adds a FencedBlockExtension to flexmark-java that converts diagram- image descriptions to SVG diagrams via https://kroki.io/.

The advantage of the diagram- prefix is that it allows KeenWrite to automatically get new text-based diagram image formats without having to rebuild and redistribute the software. When kroki gets a new format, KeenWrite simply calls out to it by matching against the diagram- suffix.

Here's a screenshot showing a family tree rendered using diagram-graphviz:

That is, the Markdown document contains:

``` diagram-graphviz
digraph G2 {
  edge [dir=none, color="#`r#x(v$palette$body)`", fontcolor="#`r#x(v$palette$body)`"];
  node [shape=box, style="filled", margin="0.2, 0.225", fontname="Roboto", color="#`r#x(v$palette$body)`", fillcolor="#eef4d7"];
  graph [splines=ortho];
   ...
}

This supports all formats offered by Kroki: PlantUML, GraphViz, Mermaid (rendering issues due to non-compliance notwithstanding), etc. When the next version of EchoSVG is released, it should fix some of the Mermaid rendering issues.

Aside, KeenWrite will send your diagram text to kroki.io for rendering. KeenWrite has a podman integration to ease typesetting. That same container could, in the future, be used to handle requests to a local kroki web server, ensuring that no content goes over the Internet.

[kwin]

@DaveJarvis Thanks a lot for the info and implementation. Any chance you can decouple that flexmark extension from the UI and provide that as dedicated artifact?

[ghost]

Any chance you can decouple that flexmark extension from the UI and provide that as dedicated artifact?

Good idea. I won't be taking this on, but feel free to add an issue to KeenWrite's issue tracker, where it may get some traction. If you'd like some guidance, open the ticket and I can direct you to what you'll need to do, depending on your requirements.

FWIW, KeenWrite can be run from the command-line without opening the UI, if that's your concern.