Mermaid: Like Markdown for Diagrams

2014-11-28 00:00:00 +0000 by Alex R. Young


When I work on books my editor always seems to push for more diagrams. Diagrams are useful, but drawing tools are a chore to use. When I get really stuck I resort to pen and paper or ASCII art. Writing suffers from the same issue: people love playing with writing tools and fonts before realising writing in Markdown or something similar is far more productive.

That's why I thought Mermaid (GitHub: knsv/mermaid, License: MIT, Bower: mermaid) sounded cool:

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

Ever wanted to simplify documentation and avoid heavy tools like Visio when explaining your code?

This is why mermaid was born, a simple markdown-like script language for generating charts from text via javascript.

Rather than playing with stroke styles and colours, fonts, and other distractions, you can focus on the meaning the diagram is trying to encapsulate. Mermaid does allow you to include styles so you can change fill colours and strokes, but the text-based syntax might be easier to work with than GUI drawing tools under some circumstances.

I noticed Mermaid has two Jison files, which seems like a sensible way to parse the diagram syntax. For example, flow.jison is used to generate the parser that parses text graph definitions.

d3 is used for drawing, so you should be able to use Mermaid anywhere you use d3. It comes with a Gulpfile for generating optimised builds, and there are some Karma tests as well.