Awesome, Text-Based Diagrams with Mermaid

By December 20, 2016Visual Studio Code

A picture is worth a thousand words. Plain text can convey high levels of detail, but when there are multiple entities involved, text fails to communicate the relationships between them well. In a recent incident, I needed to explain to myself and others how information flowed between four different actors in a transaction. Oral and written attempts would quickly become confusing because of the difficulty of keeping the state of all the different actors in our heads at once. In comparison, once the transaction was laid out in a diagram, the flow of information immediately become far easier to understand for all involved. This is the power of diagrams.

However, creating and sharing diagrams can be pretty frustrating. Most tools that I’ve used have required heavy mouse-based interaction and fiddling with dragging lines here and there in an attempt to keep things looking neat. Then comes the problem of distribution: Save the diagram in its native format or export it to an image? The first option requires everyone to have the same diagramming software but retains the ability to edit. The second option makes the diagram viewable by everyone, but loses the ability to edit. Wouldn’t it be great if there was a way to create diagrams just by typing some simple markup, and have it render a diagram anyone can view? There is a way thanks to a project called Mermaid.

Mermaid is at its heart a markup language for creating three kinds of diagrams: Flowcharts, sequence diagrams (good for representing a sequence of interactions between multiple entities), and Gant charts. It is implemented as a NPM module which exposes a JavaScript API as well as a CLI which can render diagrams into PNG or (experimental) SVG. There’s a live editor you can use to play around and generate output with. That’s nice, but my main interest is in adding diagrams to documentation, especially project documentation. And here’s the exciting news (at least for me): there is already a plugin for VSCode that supports (pre)viewing the diagrams–including those embedded in Markdown documents–in a dedicated pane, and another plugin that previews Markdown plus Mermaid diagrams in one unified view! At present, the preview in the dedicated view yields a more accurate result than the one that displays Markdown and Mermaid in one view–the unified view doesn’t currently render directional arrows.


Even lacking the arrows, having the ability to view embedded diagrams in Markdown is fantastic, and I hope that those little pointy guys will make an appearance soon. Until then, there’s always Mermaid Preview in a dedicated pane whenever you need to see the directional arrows. This is a fantastic addition to your toolkit for creating more informative documentation.

The following two tabs change content below.