Mermaid — Create Charts and Diagrams With Markdown-like Syntax

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

Indrek Lasn
Oct 30, 2019 · 4 min read
Source: Mermaid

Mermaid lets you generate diagrams and flowcharts with Markdown-like syntax. It’s easy to use, free, and open source. Mermaid lets you simplify documentation and avoid bulky tools when explaining your code.

Source: Mermaid Github Page

Examples

Here are a couple of examples of what you can do with Mermaid.

Flowchart

A flowchart is a type of diagram that represents a workflow or process. A flowchart can also be defined as a diagrammatic representation of an algorithm — a step-by-step approach to solving a task.

graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
Mermaid Flowchart Graph

Sequence Diagram

A sequence diagram simply depicts the interaction between objects in sequential order; i.e. the order in which these interactions take place.

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!
Mermaid Sequence Graph

Gantt Diagram

A Gantt chart is a type of bar chart that illustrates a project schedule. It’s named after its inventor, Henry Gantt, who designed such a chart around the years 1910–1915. Modern Gantt charts also show the dependency relationships between activities and current schedule status.

gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10
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
Mermaid Gantt Graph

Class Diagram (Experimental)

A class diagram in the Unified Modeling Language (UML) is a type of static structure diagram that describes the structure of a system by showing the system’s classes, their attributes, operations (or methods), and the relationships among objects.

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()
}
Mermaid Class Graph

Git Graph (Experimental)

Git graphs are a way to visualize your Git project commits, merges, and progress.

gitGraph:
options
{
"nodeSpacing": 150,
"nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch
Mermaid Git Graph

How to Install Mermaid

NPM

yarn add mermaid

CDN

<script  src=”https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.3.1/mermaid.min.js"></script>

Simple usage on a web page

The easiest way to integrate Mermaid on a webpage requires two elements:

  1. Inclusion of the Mermaid framework in the HTML page using a script tag.
  2. A graph definition on the webpage.

If these things are in place, Mermaid listens to the page load event, and when fired (when the page has loaded), it will locate the graphs on the page and transform them into SVG files.

Include Mermaid on your web page:

<script  src=”https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.3.1/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

Further down on your page, Mermaid will look for tags with class="mermaid". From these tags, Mermaid will try to read the chart definition and replace it with the SVG chart.

Define a chart like this:

<div class="mermaid">
CHART DEFINITION GOES HERE
</div>

The chart would then end up like this:

<div class="mermaid" id="mermaidChart0">
<svg>
Chart ends up here
</svg>
</div>

An id attribute is also added to mermaid tags without one.

Simple full example:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
</head>
<body>
<div class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</div>
<script src="mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>
</body>
</html>

Usage with webpack

Mermaid fully supports webpack. Here is a working demo.

For contributors

Detailed information about contributing can be found in the contribution guide


For an in-depth guide and explanation, check out the official Mermaid documentation. Thanks for reading, and happy coding!

Better Programming

Advice for programmers.

Indrek Lasn

Written by

Web & iOS Engineer, connect with me on Twitter @ https://twitter.com/lasnindrek

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade