I’m the main author of KeenWrite (see screenshots[1]), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.
First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485[2]. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).
Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)
Third, see the CommonMark discussion thread[3] referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.
Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:
The diagram- prefix tells KeenWrite that the content is a diagram. The prefix is necessary to allow using any diagram supported by a Kroki server without having to hard-code the supported diagram type within KeenWrite. Otherwise, there is no simple way to allow a user to mark up a code block with their own text style that may coincide with an existing diagram type name.
Fifth, if ever someone wants to invent a programming language named Mermaid (see MeLa), then it precludes the possibility of using the following de facto syntax highlighting:
``` mermaid
```
My feature request is to add support for Kroki and the diagram- prefix syntax. That is:
``` diagram-mermaid
```
And deprecate the following syntax:
``` mermaid
```
And, later, introduce the language- prefix for defining code blocks that highlight syntax. That is, further deprecate:
``` java
```
With the following:
``` language-java
```
That would provide a “namespace” of sorts to avoid naming conflicts in the future.
I’m the main author of KeenWrite (see screenshots[1]), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS.
First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485[2]. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future).
Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.)
Third, see the CommonMark discussion thread[3] referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed.
Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax:
The diagram- prefix tells KeenWrite that the content is a diagram. The prefix is necessary to allow using any diagram supported by a Kroki server without having to hard-code the supported diagram type within KeenWrite. Otherwise, there is no simple way to allow a user to mark up a code block with their own text style that may coincide with an existing diagram type name.Fifth, if ever someone wants to invent a programming language named Mermaid (see MeLa), then it precludes the possibility of using the following de facto syntax highlighting:
My feature request is to add support for Kroki and the diagram- prefix syntax. That is: And deprecate the following syntax: And, later, introduce the language- prefix for defining code blocks that highlight syntax. That is, further deprecate: With the following: That would provide a “namespace” of sorts to avoid naming conflicts in the future.[1]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...
[2]: https://github.com/mermaid-js/mermaid/issues/2485
[3]: https://talk.commonmark.org/t/mermaid-generation-of-diagrams...