As developers, we often need to explain complex ideas visually. Whether it’s showing how an algorithm works or mapping out a project timeline, diagrams can be a lifesaver. That’s where Mermaid comes in. It’s a tool that lets you create charts and diagrams using a simple, Markdown-like syntax. Best part? It’s free, open-source, and works with just text.

What is Mermaid?

Mermaid allows you to generate charts directly from text using JavaScript. You don’t need to deal with heavy diagramming tools or drag-and-drop interfaces. Just write a few lines of text, and Mermaid turns it into a chart.

I personally love this tool because it keeps my documentation lightweight. No need to juggle different tools just to explain a flow or concept. Plus, since it’s open-source, you can easily integrate it into your own projects.

Examples

Here are some practical examples of what you can create with Mermaid. Note: Click on the charts to open them in Live Editor!

Flowchart

A flowchart is great for showing how processes or algorithms work. It’s a simple way to represent a sequence of steps.

1
graph TD;
2
    A-->B;
3
    A-->C;
4
    B-->D;
5
    C-->D;

This flowchart shows a basic process where “A” can lead to both “B” and “C”, and both “B” and “C” lead to “D”. With just a few lines of text, you’ve got a clear visual representation.

Sequence Diagram

If you’re working on a system with multiple interactions between components or people, a sequence diagram can help.

1
sequenceDiagram
2
    participant Alice
3
    participant Bob
4
    Alice->>John: Hello John, how are you?
5
    loop Healthcheck
6
        John->>John: Fight against hypochondria
7
    end
8
    Note right of John: Rational thoughts <br/>prevail!
9
    John-->>Alice: Great!
10
    John->>Bob: How about you?
11
    Bob-->>John: Jolly good!

This shows a conversation between Alice, Bob, and John. Sequence diagrams are perfect when you want to depict how different actors interact with each other in a specific order.

Gantt Chart

If you’re managing a project, Gantt charts help you visualize timelines and dependencies.

1
gantt
2
dateFormat  YYYY-MM-DD
3
title Adding GANTT diagram to Mermaid
4
section A section
5
Completed task            :done,    des1, 2014-01-06,2014-01-08
6
Active task               :active,  des2, 2014-01-09, 3d
7
Future task               :         des3, after des2, 5d
8
Future task2              :         des4, after des3, 5d

This chart shows tasks with start and end dates, as well as which tasks depend on others. It’s useful for project planning and tracking.

Class Diagram

If you work with object-oriented programming, a class diagram shows relationships between classes.

1
classDiagram
2
Class01 <|-- AveryLongClass : Cool
3
<<interface>> Class01
4
Class03 *-- Class04
5
Class05 o-- Class06
6
Class07 .. Class08
7
Class09 --> C2 : Where am i?
8
Class09 --* C3
9
Class09 --|> Class07
10
Class07 : equals()
11
Class07 : Object[] elementData
12
Class01 : size()
13
Class01 : int chimp
14
Class01 : int gorilla
15
Class08 <--> C2: Cool label
16
class Class10 {
17
  <<service>>
18
  int id
19
  size()
20
}

This diagram shows how different classes relate to one another. You can visualize inheritance, composition, and method declarations.

Git Graph

Working on a Git project? A Git graph visualizes commits, merges, and branches in a clear and concise way.

1
---
2
title: Git diagram
3
---
4
gitGraph
5
   commit
6
   commit
7
   branch develop
8
   checkout develop
9
   commit
10
   commit
11
   checkout main
12
   merge develop
13
   commit
14
   commit

This graph makes it easy to track how branches and merges happen over time.

How to Install Mermaid

You can install Mermaid in a couple of ways:

• For projects using npm or Yarn, just run:

1
npm i mermaid

1
yarn add mermaid

• You can also include Mermaid in your project via a CDN:

Simple Usage on a Web Page

To use Mermaid on a webpage, include it like this:

Then, define a chart like this:

1
<pre class="mermaid">
2
  graph LR
3
      A --- B
4
      B-->C[fa:fa-ban forbidden]
5
      B-->D(fa:fa-spinner);
6
</pre>

When the page loads, Mermaid will automatically convert the chart definition into an SVG.

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
  <meta charset="utf-8">
5
</head>
6
<body>
7
  <pre class="mermaid">
8
    graph LR
9
      A --- B
10
      B-->C[fa:fa-ban forbidden]
11
      B-->D(fa:fa-spinner);
12
  </pre>
13
</body>
14
</html>

Usage with Webpack

Mermaid fully supports Webpack. This allows you to bundle Mermaid into your existing projects easily. Just install it with npm and import it into your project.

Conclusion

Mermaid diagrams now render natively in GitHub, GitLab, Notion, and VS Code without any setup. Since this article was written, Mermaid has added many new diagram types including state diagrams, mindmaps, timelines, sankey diagrams, and more.

Mermaid is a powerful tool for generating diagrams without leaving your code editor. Whether you’re explaining a workflow, modeling classes, or planning a project, Mermaid makes it simple. If you want to dive deeper, check out the official Mermaid documentation.