Mermaid: The All-in-One Tool To Create Any Diagram

Solving several problems with prior diagramming tools. Mermaid is a must-learn for any engineer

Photo by Annette Batista Day on Unsplash

For decades, engineers have been creating diagrams for various use cases. A diagram can convey that information quickly and succinctly, whether it’s to document architecture or explain a complex sequence of events.

For many of those decades, the creation of diagrams was done manually. You need to download software or use an online UI-based tool to create diagrams. When you were finished, you exported your diagram as an image to share with your colleagues.

This presented several problems that prevented diagramming from becoming something most engineers did. Nowadays, though, there is a better way, and it’s called Mermaid.

What is Mermaid?

Before we dive into how I believe Mermaid is a significant improvement, let’s take a closer look at Mermaid.

Mermaid is a diagramming tool that you can use to create diagrams. However, instead of drawing a diagram manually, you use Markdown-like markup to define a diagram, and Mermaid takes that markup and renders a diagram.

For example, here’s some Mermaid markup to create a simple flowchart:

flowchart LR
   hungry{Are you hungry?}

   hungry-- "Yes" -->Eat
   hungry-- "No" -->Sit

When rendered, it looks like this:

Image credit: author

It’s simple but effective. Most importantly, anyone could create a diagram using Mermaid and a browser. Their documentation is also very good, allowing you to get up to speed quickly.

Mermaid supports various diagrams besides a flowchart, such as sequence diagrams, class diagrams, and entity relationship diagrams. If Mermaid doesn’t natively support the type of diagram you want, you can likely create it using a flowchart. For example, I’ve used Mermaid’s flowchart to create C4 model diagrams before native support was added (The C4 diagrams are still experimental in Mermaid!).