Mermaid: The All-in-One Tool To Create Any Diagram | by Ashley Peacock | Nov, 2022

Solving many problems with earlier diagramming tools. Jalpari is a must for any engineer

photo by annette batista day Feather unsplash

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

For many of those decades, the construction of diagrams was done manually. You need to download software or use online UI-based tools to create diagrams. When you’re finished, you export your diagram as an image to share with your coworkers.

This presented a number of problems that prevented drawing from becoming something that most engineers did. Nowadays, though, there’s a better way, and it’s called mermaids.

Before we get into why 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 manually drawing the diagram, you use Markdown-like markup to define the diagram, and Mermaid takes that markup and renders the diagram.

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

flowchart LR
hungryAre 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 can create diagrams using Mermaid and a browser. their Documentation It’s also great, so you can get up to speed quickly.

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

Now we know what mermaid is, but what problems does it solve as a UI-based tool or even plantuml,

If you’ve created diagrams before and used UI-based tools, I’m sure you’ve also experienced the pain of losing the original source. I have, of course, either forgotten to save it or, if it’s at work, a colleague is leaving and the diagram is lost with them.

This situation occurs because the rendered diagram must be manually exported from the UI-based tool, and the resulting image must be uploaded somewhere (for example, in some document). This means that the source and rendered diagrams are separated at that point. You can commit both the image and the source to version control, but chances are they will get out of sync at some point.

Also, have you ever tried diffing the source files with a UI-based tool? I guarantee you it’s irreversible, and not human-readable at all. Which makes review impossible.

Jalpari solves both of those problems.

First, as you can see in the example above, the source of Mermaid is the same as Markdown, which makes it diffrent and reviewable.

secondly, and most importantly, the mermaid has significant adoption already. GitHub has native supportT for mermaid (does as gitlab, There are IDE plugins for VS Code, Sublime, Vim and many more. It even has support (some native) in Jira, Trello, Notion and many other productivity tools.

Native GitHub and GitLab support is the real killer feature. You can commit your mermaid diagrams to Markdown files, and they will render your diagram when viewed (for example, in a readme). This makes it impossible for the source to be out of date, as it is being submitted from source, and is easily reviewed in a pull request.

PlantUML, an old tool for creating diagrams from simple markup, does a really similar job to Mermaid. The main difference is that it was released in 2009, and the rendering is done using Java. With Mermaid, you can render diagrams from source in the browser. In my opinion, that’s why Mermaid has been so widely adopted.

It’s not that PlantUML is bad. far from it. It’s just that the adoption of Mermaid is growing rapidly, making it the dominant tool for diagramming.

Mermaid is revolutionizing how diagrams are created and presented. The speed at which diagrams can be created decreases exponentially with Mermaid because, unlike UI-based tools, you don’t have to worry about how it looks.

Excited to try Mermaid but not sure where to start?

My book, Creating Software with Modern Diagramming Techniques, is out now! click here All while using mermaids to learn how to draw diagrams to communicate information more directly and clearly than words.

Leave a Reply