What is Mermaid(.js)?
Mermaid is a JavaScript library that converts text, strict markdown-like syntax, to diagrams. It is similar to PlantUML but has broader use, popularity, and support.
Compared to traditional diagramming tools like Visio and Draw.io, where you create diagrams by drawing elements and relationships, with Mermaid, you create diagrams by strictly defining elements and their relationships with code. The Diagram as code is the Mermaid's greatest strength and the most significant weakness. It's fantastic because if you know all the elements and relationships, it's easy to define them with code. Creating tools for generating mermaid diagrams from existing code or data is simple. You can even use LLMs:
Give me c# factory example with Mermaid diagrams.
classDiagram
class IProduct {
<<interface>>
+Operation()
}
class ConcreteProductA {
+Operation()
}
class ConcreteProductB {
+Operation()
}
class ProductFactory {
+CreateProduct(string)
}
IProduct <|-- ConcreteProductA
IProduct <|-- ConcreteProductB
ProductFactory --> IProduct : creates
Simple LLM Input and Result
Mermaid Diagram from LLM
However, as a visual thinker, I find it hard to be creative with Mermaid. When brainstorming, I'm much more comfortable with something like Whimsical, where I can focus on elements and relationships by dragging and dropping. Also, for more complex diagrams, or diagrams where I need to be precise about where I want to put the elements, Mermaid is not that useful. As developers, we often neglect that data visualizations are stories you need to tell, not just truthful representations of the facts.
Mermaid, as a text-based tool, is version control friendly. It integrates into most CI/CD, Markdown, documentation tools, popular CMS, Static Site Generators, IDEs, and Text Editors. Most of the diagrams for this blog are created with Mermaid.
Mermaid is in active development and frequently adds new diagrams and features.
Key Diagram Types and Examples
As of 11.4.1, supported Diagrams
- Flowchart
- Sequence Diagram
- Class Diagram
- State Diagram
- Entity Relationship Diagram
- User Journey
- Gantt
- Pie Chart
- Quadrant Chart
- Requirement Diagram
- Gitgraph (Git) Diagram
- C4 Diagram 🦺⚠️
- Mindmaps
- Timeline
- ZenUML
- Sankey 🔥
- XY Chart 🔥
- Block Diagram 🔥
- Packet 🔥
- Kanban 🔥
- Architecture 🔥
C4 Diagram is experimental, and diagrams with Fire Emojis are not supported on older versions.
Kanban Diagram
I especially like the new Kanban diagram. As someone who does not want to use heavy tools for project management, this is a great way to keep track of tasks and progress. My PO is not amused.
Creating even complex diagrams like Kanban is easy:
---
config:
kanban:
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
---
kanban
Todo
[Create Documentation]
docs[Create Blog about the new diagram]
[In progress]
id6[Create renderer so that it works in all cases. We also add som extra text here for testing purposes. And some more just for the extra flare.]
id9[Ready for deploy]
id8[Design grammar]@{ assigned: 'knsv' }
id10[Ready for test]
id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
id11[Done]
id5[define getData]
id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
id12[Can't reproduce]
id3[Weird flickering in Firefox]
Conclusion
I love the Mermaid. It's one of my favorite tools for documentation. With growing tool support and LLMs that "speak Mermish," I expect it to be used even more!
We developers often think code is the only way to present information. In many cases, graphical representation is not only more straightforward but more practical in representing ideas. Mermaid is an excellent tool for achieving this.