Mermaid.js: Charts and Diagrams from Markdown-like Syntax

Mermaid.js is a simple markdown-like script language for generating charts from text via JavaScript

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.

Update: Mermaid 12 and the missing loader script

The script tags this post refers to had gone missing, so the examples below now include the loader from the Mermaid docs, which imports the ES module build from jsDelivr.

Mermaid 12.0.0, released in September 2026, makes the ELK layout and a new look the defaults, so existing diagrams re-lay out and change color. It needs Safari 17.4 or newer.

To keep the old style, pass these options to mermaid.initialize:

mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' });

The 12.0.0 release notes list every change.

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.

graph TD;
A-->B;
A-->C;
B-->D;
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.

sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
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.

gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram to Mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
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.

classDiagram
Class01 <|-- AveryLongClass : Cool
<<interface>> Class01
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
class Class10 {
<<service>>
int id
size()
}

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.

---
title: Git diagram
---
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
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:
Terminal window
npm i mermaid

Terminal window
yarn add mermaid
  • You can also include Mermaid in your project via a CDN:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>

Simple Usage on a Web Page

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

<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>

Then, define a chart like this:

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

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

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
</head>
<body>
<pre class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</pre>
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</body>
</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.


Trevor I. Lasn

Trevor I. Lasn

Building whiteheap.com and 0xinsider.com.



Related Articles

Check out these related articles that might be useful for you. They cover similar topics and provide additional insights.

Developer tools
20 min read

residue-cli removes a Git worktree only when nothing in it would be lost. How its 15 checks decide, how it deletes and restores, and residue-ui for the Mac.

Nov 9, 2026
Read article
JavaScript
4 min read

Intermediate variables name each step of complex logic, and early returns handle failing cases first. A JavaScript authentication check, rewritten both ways.

Aug 30, 2024
Read article
React
7 min read

Run a React app in Docker: write a Dockerfile, start it with Docker Compose, serve the production build with Nginx and deploy it to a VPS.

Jul 16, 2020
Read article
Developer tools
5 min read

Pkl, pronounced pickle, is Apple's open source configuration-as-code language, with schemas, validation and immutable values. How it compares to JSON and YAML.

Nov 1, 2024
Read article
Developer tools
6 min read

Repomix, formerly Repopack, packs a whole code repository into one file you can share with Claude or ChatGPT. Usage, key features and a word of caution.

Oct 21, 2024
Read article
JavaScript
4 min read

Stop mixing try/catch with Promise chains - JavaScript's new Promise.try handles return values, Promises, and errors uniformly

Nov 10, 2024
Read article
Developer tools
5 min read

eslint-plugin-depend flags npm packages like is-odd that plain JavaScript replaces. How to install and configure it, and its move to @e18e/eslint-plugin.

Aug 13, 2024
Read article
Web performance
3 min read

rel=modulepreload fetches, parses and compiles an ES module before a script imports it. How to use it, and why each module in the graph needs its own link.

Dec 4, 2024
Read article
Developer tools
13 min read

List of useful Unix terminal commands to boost your productivity. Here are some of my favorites.

Aug 21, 2024
Read article

This article was originally published on https://www.trevorlasn.com/blog/mermaid-create-charts-and-diagrams-with-markdown. It was written by a human and polished using grammar tools for clarity.