# GitHub adding support for Mermaid diagrams **URL:** \ **Category:** Show and Tell\ **Created:** [January 16, 2022, 10:43pm UTC](https://forum.graphviz.org/t/github-adding-support-for-mermaid-diagrams/998 "2022-01-16T22:43:35Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![mark](https://sea2.discourse-cdn.com/graphviz/user_avatar/forum.graphviz.org/mark/32/84_2.png) [@mark](https://forum.graphviz.org/u/mark)\ **Post date:** [January 16, 2022, 10:43pm UTC](https://forum.graphviz.org/t/github-adding-support-for-mermaid-diagrams/998/1 "2022-01-16T22:43:35Z")
GitHub will be baking in support for Mermaid diagrams into their Markdown variant rendered for README.md etc. > > > \### Summary > > \[Mermaid\](https://mermaid-js.github.io/) is an incredibly popular… Markdown-inspired syntax used to visualize workflows, software architecture, and abstract concepts in documentation. Support for displaying Mermaid diagrams has appeared on GitHub's top list of feature requests \[since 2015\](https://github.com/github/markup/issues/533). In its absence, many developers simply added screenshots to their Markdown. Today, we're excited to add native support for Mermaid wherever Markdown is supported (e.g., issues, repositories, discussions, gists). > > \### Intended Outcome > > With this feature, GitHub will support Mermaid diagrams within Markdown fields and files. > > \### How will it work? > > Just as \[language-specific code blocks\](https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting) can be added to Markdown, you'll be able to add a Mermaid diagram using a code block that specifies \`mermaid\` as its language identifier. For example: > > \`\`\`\`\`\` > \`\`\`mermaid > graph TD; > A--\>B; > A--\>C; > B--\>D; > C--\>D; > \`\`\` > \`\`\`\`\`\` > > The Markdown code block above uses Mermaid syntax to display this flowchart in the rendered Markdown: > > !\[image\](https://user-images.githubusercontent.com/1767415/147986289-f8283c0b-aa5e-4381-bd69-876edeef12d9.png) > > \[Another example\](https://mermaid-js.github.io/mermaid/#/sequenceDiagram?id=sequencenumbers) from the Mermaid website shows how straightforward text can be used to create rich diagrams: > > \`\`\`\`\`\` > \`\`\`mermaid > sequenceDiagram > autonumber > Alice-\>\>John: Hello John, how are you? > loop Healthcheck > John-\>\>John: Fight against hypochondria > end > Note right of John: Rational thoughts! > John--\>\>Alice: Great! > John-\>\>Bob: How about you? > Bob--\>\>John: Jolly good! > \`\`\` > \`\`\`\`\`\` > > The Markdown code block above would display this sequence diagram in the rendered Markdown: > > \ > > For more information about Mermaid, visit its \[website\](https://mermaid-js.github.io/) or its \[open-source repository\](https://github.com/mermaid-js/mermaid). Always interesting to keep up with what the competition’s doing ;-). Mermaid is a JS library easily embeddable, with sequence diagrams, entity relationship diagrams, gantts, alongside more traditional graphviz-style directed graphs. > **[Mermaid | Diagramming and charting tool](https://mermaid.js.org/)** > > Create diagrams and visualizations using text and code. ---
**Author:** ![mark](https://sea2.discourse-cdn.com/graphviz/user_avatar/forum.graphviz.org/mark/32/84_2.png) [@mark](https://forum.graphviz.org/u/mark)\ **Post date:** [January 16, 2022, 11:01pm UTC](https://forum.graphviz.org/t/github-adding-support-for-mermaid-diagrams/998/2 "2022-01-16T23:01:48Z")
I think it’s worth asking ourselves why GitHub didn’t integrate Graphviz; maybe we can learn about our competitiveness. My guesses: My guesses: Graphviz is in C, Mermaid is in JS, Mermaid is easier to integrate. Mermaid also has a few higher-level features (Gantt charts, Entity Relationship Diagrams, Sequence Diagrams). While it’s possible to compile Graphviz to wasm/web-worker and embed on a website, it’s a pretty big library. There’s a bit of an impedance mismatch. Finally I wouldn’t be surprised if the default styling played a part. Graphviz’s default styling is, well, spartan, while Mermaid’s is a bit nicer. ---
**Author:** ![steveroush](https://avatars.discourse-cdn.com/v4/letter/s/a9adbd/32.png) [@steveroush](https://forum.graphviz.org/u/steveroush)\ **Post date:** [January 16, 2022, 11:32pm UTC](https://forum.graphviz.org/t/github-adding-support-for-mermaid-diagrams/998/3 "2022-01-16T23:32:41Z")
Interesting. Similarly, there is pikchr ([Pikchr: Documentation](https://pikchr.org/home/doc/trunk/homepage.md)), a variant of the PIC graphics language, that can also be embedded in some markdown - but not here. Pikchr consists of a single C program that produces SVG. To-date, the biggest strength of Graphviz is mid-size and large graphs. What might make Graphviz more _attractive_ for smaller diagrams? - interactive or animated results ~~(maybe not that hard?)~~ - easier author control of node and/or edge placement (infinitely challenging) - class/style capability (maybe not that hard if done as a (built-in) pre-processor?) - DIY nodes - … Personally, I like fiddling with small-to-mid sized issues, but not at the expense of the code quality or the large-sized features. ---
**Author:** ![Vithanco](https://sea2.discourse-cdn.com/graphviz/user_avatar/forum.graphviz.org/vithanco/32/292_2.png) [@Vithanco](https://forum.graphviz.org/u/Vithanco)\ **Post date:** [January 20, 2022, 9:11am UTC](https://forum.graphviz.org/t/github-adding-support-for-mermaid-diagrams/998/4 "2022-01-20T09:11:56Z")
From my perspective are the looks the biggest drawback of Graphviz. Having a few standard templates to choose from for a graph would be great. As an example, if you could with one parameter turn the visuals into a Mermaid diagram. I don’t see the wasm size as a real problem. It is compressed 388KB, uncompressed about double. ([Details · Discussion #87 · hpcc-systems/hpcc-js-wasm · GitHub](https://github.com/hpcc-systems/hpcc-js-wasm/discussions/87)) (but only my 5p).