I am super excited by this. I’m looking forward to combining this with ARCHITECTURE.md files to make some kick-ass documentation for our company’s devs for our repo(s).

Re: https://github.com/github/markup/issues/533

I’m the main author of KeenWrite (see screenshots), 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. 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 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:

``` diagram-mermaid
```

``` diagram-graphviz
```

``` diagram-plantuml
```

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.

The diagramming support is one of the things I miss most after moving from gitlab to github.

Really a shame they chose to support a new diagram language like Mermaid rather than one that has been around for 30 years, is widely used, and extremely flexible? Especially since is already a massive set of Graphviz files on Github. A simple search finds approximately 2,441,463 Graphviz files on Github (Source: https://github.com/search?q=extension%3Agv&type=Code&ref=advsearch&l=&l= and https://github.com/search?q=extension%3Adot&type=Code&ref=advsearch&l=&l=). A Github search for Mermaid on turns up only 7,846 files (https://github.com/search?q=extension%3Ammd&type=Code&ref=advsearch&l=&l=), making extremely unpopular by comparison. Why would Github ignore Graphviz and choose to support Mermaid instead?

Perhaps they looked at the number of Graphviz files in existence and realized that due to it’s popularity, they’d have to have a lot more infrastructure in place and the cost would be much greater? For example, if you figured rendering a diagram cost 1 cent (just as an example, I have no idea how much it costs). Rendering their library of Mermaid would only cost them about $78. Whereas Graphviz would end up costing them $24,414.63. Perhaps there are other technical constraints here I am not aware of? Maybe they’ve already got good infrastructure in place for JS libraries, and therefore Mermaid is an easier implementation.

They’re really getting onto the long … tail … of features now ;)

This is great! I’ve been working around the lack of this feature for years.

now we just need mermaid in Rust docs. Mermaid everywhere.

perennial request for corporate tag

Hmm. Seems useful, but also I think I’d rather use SVG for more portability? But then, this seems more accessible.

I don’t use GitHub but this is the first time I’ve heard of Mermaid and honestly I wish I knew about this a few years ago.

This is fantastic! I use this a lot in Markdown on GitLab, which already supports this. It’s great for design documents.

The big advantage of Mermaid is that it’s done completely in the browser, so the cost is minimal for GitHub. PlantUML, Graphviz, etc would need a server side rendering component.

Unfortunately Mermaid is not quite as mature as PlantUML and some stuff doesn’t work that well. It really isn’t good enough for publication-quality output. Hopefully this will bring renewed interest and it can improve!

This looks useful!

I assumed this was a new diagram type. Turns out to just be a politically correct and acceptable name for much of poor old UML.

[Comment removed by moderator pushcx: Don't post dismissive snark.]