Mermaid - Generation of diagrams and flowcharts from text in a similar manner as markdown

62

I agree that curly braces are looking too technical. With tilde fences ~~~, there is also no ambiguity with inline code spans.

Meanwhile, Github has started advertising its Mermaid support in GFM without any special marker like !:

4 Likes
63

It appears they are rendering it to HTML as a code block literal (i.e. the same as theyā€™d do for ```rust), and the diagram you see in the browser is a client-side Javascript rendering. What you see is dependent on the type of request and whether its from a Javascript-enabled client.

2 Likes
64

Meanwhile, Github has started advertising its Mermaid support in GFM without any special marker like !

Yeah - that was based off this discussion. You can find details of the implementation here.

While previously Iā€™d been a fan of the ```! syntax to symbolize rendering rather than syntax highlighting, the thing that convinced me was all the prior art without the bang but also we didnā€™t support nor had any plans to support syntax highlighting of Mermaid script in particular. So the answer to the question of ā€˜how do I show a block of Mermaid codeā€™ was to do ```.

Possibly pragmatic I know, but as doing it this way didnā€™t need us to change the CommonMark spec either and the fact it would already work in a bunch of other places (include editor extensions and other hosting services like Discourse, Azure DevOps Wikiā€™s or GitLab) went ahead and shipped it.

3 Likes
65

This is an excellent example of how failure to define a standard soon enough will result in a more ad hoc one getting established instead.

4 Likes
66

This is true statement, but it does not give ideas what can be done now & in future. If you inspect history, existing spec is created from ā€œpast infoā€. And we need to land new extensions (not de-facto standards).

Thatā€™s a next spin with new start conditions - not enough prior arts to refer. May be math has chance to be landed. But situation with fenced blocks (literals [diagrams]), fenced containers (markdown [quotes]) and inlines is still uncertain.

3 Likes
67

Just came here to say that I totally prefer option D due to backwards compatibility and explicitness. Right now, it is too late (I think) to really enforce a single specific option. In the current spec, it is said that the info string is not enforced in any way, and it includes many links to the non-existent info string heading So I think going forward with this should solve those two problems:

  1. Drawing/execution of code is opt-in clarified
  2. Working with option D is also forward-compatible (Already adding mermaid () or mermaid = gives current (undefined) behaviour)
  3. It eliminated current undefined behaviour: the single example 143 does suggest that anything after the first word should be removed in the render, but this is nowhere explicit. Also this gives the questions:

How should the info string be treated? Does interpreting the second part mean you donā€™t comply with the specification? If the second token is not () or =, but it is a separate token somewhere else, should it still be interpreted in that way?