---
title: "Mermaid.js: Charts and Diagrams from Markdown-like Syntax"
description: "Mermaid.js is a simple markdown-like script language for generating charts from text via JavaScript"
canonical: "https://www.trevorlasn.com/blog/mermaid-create-charts-and-diagrams-with-markdown"
author: "Trevor I. Lasn"
published: "2019-10-30"
last-updated: "2026-11-08"
topics: ["Developer tools", "JavaScript"]
---

# 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

By Trevor I. Lasn · Published 2019-10-30 · Updated 2026-11-08 · https://www.trevorlasn.com/blog/mermaid-create-charts-and-diagrams-with-markdown

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**](https://mermaid.js.org/) 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](https://mermaid.js.org/intro/getting-started.html), 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`:

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

The [12.0.0 release notes](https://github.com/mermaid-js/mermaid/releases/tag/mermaid%4012.0.0) 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.

```mermaid
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.

```mermaid
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.

```md
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.

```md
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.

```md
---
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:

```bash
npm i mermaid 
```

<br />

```bash
yarn add mermaid 
```

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

```html
<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:

```html
<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:

```html
<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.

```html
<!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>
```
<br />

### 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](https://mermaid.js.org/intro/).
