mermaid

Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown

70,541

6,311

70,541

1,033

View on GitHub View on NPM

Top Related Projects

drawio

40,552

draw.io is a JavaScript, client-side editor for general diagramming.

plantuml

10,277

Generate diagrams from textual description

kroki

2,857

Creates diagrams from textual descriptions!

excalidraw

80,700

Virtual whiteboard for sketching hand-drawn like diagrams

Quick Overview

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. It allows users to create various types of diagrams, including flowcharts, sequence diagrams, Gantt charts, and more, using a simple and intuitive syntax.

Pros

Easy to learn and use, with a text-based syntax that's similar to Markdown
Supports a wide variety of diagram types, including flowcharts, sequence diagrams, Gantt charts, and more
Integrates well with many popular platforms and tools, such as GitHub, GitLab, and VS Code
Generates SVG output, which is scalable and can be easily styled with CSS

Cons

Limited customization options compared to more advanced diagramming tools
Performance can be slow for very large or complex diagrams
Some diagram types may have limitations in terms of layout and styling options
Learning curve for more advanced features and diagram types

Code Examples

Creating a simple flowchart:

graph TD
    A[Start] --> B{Is it raining?}
    B -->|Yes| C[Bring an umbrella]
    B -->|No| D[Enjoy the weather]
    C --> E[End]
    D --> E

Generating a sequence diagram:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: Great!
    Alice->>Bob: Do you like diagrams?
    Bob-->>Alice: Of course!

Creating a Gantt chart:

gantt
    title A Simple Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2023-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2023-01-12  , 12d
    another task     : 24d

Getting Started

To use Mermaid in your project, follow these steps:

Include the Mermaid JavaScript file in your HTML:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

Initialize Mermaid:

<script>
    mermaid.initialize({ startOnLoad: true });
</script>

Create a diagram using the Mermaid syntax within a <div> element with the class mermaid:

<div class="mermaid">
    graph TD
        A[Start] --> B{Decision}
        B -->|Yes| C[Do something]
        B -->|No| D[Do nothing]
        C --> E[End]
        D --> E
</div>

That's it! Mermaid will automatically render the diagram when the page loads.

Competitor Comparisons

drawio

40,552

draw.io is a JavaScript, client-side editor for general diagramming.

Pros of draw.io

More comprehensive drawing capabilities, supporting a wider range of diagram types
Offers both web-based and desktop applications for enhanced flexibility
Provides a user-friendly drag-and-drop interface for easier diagram creation

Cons of draw.io

Steeper learning curve due to its extensive feature set
Requires more system resources and may be slower for simple diagrams
Less suitable for quick, text-based diagram generation in documentation

Code Comparison

draw.io uses XML-based format for diagram representation:

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Start" style="rounded=1;" vertex="1" parent="1">
      <mxGeometry x="120" y="120" width="80" height="40" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

Mermaid uses a simpler, text-based syntax:

graph TD
    A[Start] --> B[Process]
    B --> C[End]

Both repositories offer powerful diagramming capabilities, but cater to different use cases. draw.io is more suitable for complex, visually rich diagrams, while Mermaid excels in quick, code-friendly diagram generation for documentation and markdown files.

plantuml

10,277

Generate diagrams from textual description

Pros of PlantUML

Supports a wider variety of diagram types, including network diagrams and Gantt charts
Offers more customization options for diagram styling and layout
Can be integrated with various IDEs and text editors

Cons of PlantUML

Requires Java runtime environment, which can be a barrier for some users
Syntax can be more verbose and less intuitive for beginners
Rendering process is typically slower compared to Mermaid

Code Comparison

Mermaid example:

graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    B -->|No| D[End]

PlantUML example:

@startuml
start
if (Is it?) then (yes)
  :OK;
else (no)
  :End;
endif
@enduml

Both Mermaid and PlantUML are powerful tools for creating diagrams using text-based syntax. Mermaid excels in simplicity and browser-based rendering, making it ideal for quick, web-friendly diagrams. PlantUML offers more diagram types and customization options but requires additional setup. The choice between them depends on specific project needs and user preferences.

kroki

2,857

Creates diagrams from textual descriptions!

Pros of Kroki

Supports a wider range of diagram types (20+) compared to Mermaid's more limited selection
Offers server-side rendering, which can be beneficial for complex diagrams or high-traffic sites
Provides multiple output formats (SVG, PNG, PDF) for greater flexibility

Cons of Kroki

Requires server-side setup and maintenance, unlike Mermaid's client-side rendering
May have higher latency due to server-side processing, especially for simple diagrams
Less widespread adoption and community support compared to Mermaid

Code Comparison

Mermaid:

graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    B -->|No| D[End]

Kroki:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

Both examples demonstrate basic diagram creation, but Kroki uses PlantUML syntax in this case, while Mermaid uses its own syntax. Kroki supports multiple diagram languages, offering more flexibility but potentially requiring familiarity with different syntaxes.

excalidraw

80,700

Virtual whiteboard for sketching hand-drawn like diagrams

Pros of Excalidraw

More intuitive and user-friendly interface for creating diagrams
Supports freehand drawing and sketching
Offers real-time collaboration features

Cons of Excalidraw

Limited support for complex diagram types (e.g., sequence diagrams, Gantt charts)
Requires more manual effort to create structured diagrams
Less integration-friendly for developers

Code Comparison

Mermaid:

graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    B -->|No| D[End]

Excalidraw:

import { exportToBlob } from "@excalidraw/excalidraw";

const blob = await exportToBlob({
  elements,
  mimeType: "image/png",
  appState: { exportWithDarkMode: false },
});

Mermaid uses a declarative syntax to define diagrams, while Excalidraw relies on JavaScript APIs for programmatic interaction. Mermaid's approach is more suitable for quick, text-based diagram creation, whereas Excalidraw offers more flexibility for custom drawing and export options.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Mermaid

Generate diagrams from markdown-like text.

Live Editor!

ð Documentation | ð Getting Started | ð CDN | ð Join Us

ç®ä½ä¸æ

Try Live Editor previews of future releases: Develop | Next

:trophy: Mermaid was nominated and won the JS Open Source Awards (2019) in the category "The most exciting use of technology"!!!

Thanks to all involved, people committing pull requests, people answering questions! ð

Table of content

Expand contents

About
Examples
Release
Related projects
Contributors
Security and safe diagrams
Reporting vulnerabilities
Appreciation

About

Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

Doc-Rot is a Catch-22 that Mermaid helps to solve.

Diagramming and documentation costs precious developer time and gets outdated quickly. But not having diagrams or docs ruins productivity and hurts organizational learning.
Mermaid addresses this problem by enabling users to create easily modifiable diagrams. It can also be made part of production scripts (and other pieces of code).

Mermaid allows even non-programmers to easily create detailed diagrams through the Mermaid Live Editor.
For video tutorials, visit our Tutorials page. Use Mermaid with your favorite applications, check out the list of Integrations and Usages of Mermaid.

You can also use Mermaid within GitHub as well many of your other favorite applicationsâcheck out the list of Integrations and Usages of Mermaid.

For a more detailed introduction to Mermaid and some of its more basic uses, look to the Beginner's Guide, Usage and Tutorials.

Our PR Visual Regression Testing is powered by Argos with their generous Open Source plan. It makes the process of reviewing PRs with visual changes a breeze.

In our release process we rely heavily on visual regression tests using applitools. Applitools is a great service which has been easy to use and integrate with our tests.

Examples

The following are some examples of the diagrams, charts and graphs that can be made using Mermaid. Click here to jump into the text syntax.

Flowchart [docs - live editor]

flowchart LR

A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

flowchart LR

A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

Sequence diagram [docs - live editor]

sequenceDiagram
Alice->>John: Hello John, how are you?
loop HealthCheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

sequenceDiagram
Alice->>John: Hello John, how are you?
loop HealthCheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

Gantt chart [docs - live editor]

gantt
    section Section
    Completed :done,    des1, 2014-01-06,2014-01-08
    Active        :active,  des2, 2014-01-07, 3d
    Parallel 1   :         des3, after des1, 1d
    Parallel 2   :         des4, after des1, 1d
    Parallel 3   :         des5, after des3, 1d
    Parallel 4   :         des6, after des4, 1d

gantt
    section Section
    Completed :done,    des1, 2014-01-06,2014-01-08
    Active        :active,  des2, 2014-01-07, 3d
    Parallel 1   :         des3, after des1, 1d
    Parallel 2   :         des4, after des1, 1d
    Parallel 3   :         des5, after des3, 1d
    Parallel 4   :         des6, after des4, 1d

Class diagram [docs - live editor]

classDiagram
Class01 <|-- AveryLongClass : Cool
<<Interface>> Class01
Class09 --> C2 : Where am I?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
class Class10 {
  <<service>>
  int id
  size()
}

classDiagram
Class01 <|-- AveryLongClass : Cool
<<Interface>> Class01
Class09 --> C2 : Where am I?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
class Class10 {
  <<service>>
  int id
  size()
}

State diagram [docs - live editor]

stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

Pie chart [docs - live editor]

pie
"Dogs" : 386
"Cats" : 85.9
"Rats" : 15

pie
"Dogs" : 386
"Cats" : 85.9
"Rats" : 15

Git graph [experimental - live editor]

Bar chart (using gantt chart) [docs - live editor]

gantt
    title Git Issues - days since last update
    dateFormat  X
    axisFormat %s

    section Issue19062
    71   : 0, 71
    section Issue19401
    36   : 0, 36
    section Issue193
    34   : 0, 34
    section Issue7441
    9    : 0, 9
    section Issue1300
    5    : 0, 5

gantt
    title Git Issues - days since last update
    dateFormat  X
    axisFormat %s

    section Issue19062
    71   : 0, 71
    section Issue19401
    36   : 0, 36
    section Issue193
    34   : 0, 34
    section Issue7441
    9    : 0, 9
    section Issue1300
    5    : 0, 5

User Journey diagram [docs - live editor]

  journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me

  journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me

C4 diagram [docs]

C4Context
title System Context diagram for Internet Banking System

Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

Enterprise_Boundary(b1, "BankBoundary") {

  SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

  System_Boundary(b2, "BankBoundary2") {
    System(SystemA, "Banking System A")
    System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
  }

  System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
  SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

  Boundary(b3, "BankBoundary3", "boundary") {
    SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
    SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
  }
}

BiRel(customerA, SystemAA, "Uses")
BiRel(SystemAA, SystemE, "Uses")
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
Rel(SystemC, customerA, "Sends e-mails to")

C4Context
title System Context diagram for Internet Banking System

Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")

Enterprise_Boundary(b1, "BankBoundary") {

  SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

  System_Boundary(b2, "BankBoundary2") {
    System(SystemA, "Banking System A")
    System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
  }

  System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
  SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")

  Boundary(b3, "BankBoundary3", "boundary") {
    SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
    SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
  }
}

BiRel(customerA, SystemAA, "Uses")
BiRel(SystemAA, SystemE, "Uses")
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
Rel(SystemC, customerA, "Sends e-mails to")

Release

For those who have the permission to do so:

Update version number in package.json.

npm publish

The above command generates files into the dist folder and publishes them to https://www.npmjs.com.

Related projects

Contributors

Mermaid is a growing community and is always accepting new contributors. There's a lot of different ways to help out and we're always looking for extra hands! Look at this issue if you want to know where to start helping out.

Detailed information about how to contribute can be found in the contribution guide

Security and safe diagrams

For public sites, it can be precarious to retrieve text from users on the internet, storing that content for presentation in a browser at a later stage. The reason is that the user content can contain embedded malicious scripts that will run when the data is presented. For Mermaid this is a risk, specially as mermaid diagrams contain many characters that are used in html which makes the standard sanitation unusable as it also breaks the diagrams. We still make an effort to sanitize the incoming code and keep refining the process but it is hard to guarantee that there are no loop holes.

As an extra level of security for sites with external users we are happy to introduce a new security level in which the diagram is rendered in a sandboxed iframe preventing javascript in the code from being executed. This is a great step forward for better security.

Unfortunately you can not have a cake and eat it at the same time which in this case means that some of the interactive functionality gets blocked along with the possible malicious code.

Reporting vulnerabilities

To report a vulnerability, please e-mail security@mermaid.live with a description of the issue, the steps you took to create the issue, affected versions, and if known, mitigations for the issue.

Appreciation

A quick note from Knut Sveidqvist:

Many thanks to the d3 and dagre-d3 projects for providing the graphical layout and drawing libraries!

Thanks also to the js-sequence-diagram project for usage of the grammar for the sequence diagrams. Thanks to Jessica Peter for inspiration and starting point for gantt rendering.

Thank you to Tyler Long who has been a collaborator since April 2017.

Thank you to the ever-growing list of contributors that brought the project this far!

Mermaid was created by Knut Sveidqvist for easier documentation.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of draw.io

Cons of draw.io

Code Comparison

Pros of PlantUML

Cons of PlantUML

Code Comparison

Pros of Kroki

Cons of Kroki

Code Comparison

Pros of Excalidraw

Cons of Excalidraw

Code Comparison

Convert designs to code with AI

README

Mermaid

Table of content

About

Examples

Flowchart [docs - live editor]

Sequence diagram [docs - live editor]

Gantt chart [docs - live editor]

Class diagram [docs - live editor]

State diagram [docs - live editor]

Pie chart [docs - live editor]

Git graph [experimental - live editor]

Bar chart (using gantt chart) [docs - live editor]

User Journey diagram [docs - live editor]

C4 diagram [docs]

Release

Related projects

Contributors

Security and safe diagrams

Reporting vulnerabilities

Appreciation

Top Related Projects

Convert designs to code with AI

NPM DownloadsLast 30 Days