Mermaid — Generate Diagrams from Text Like Markdown

What it is

Mermaid is a JavaScript-based diagramming tool that renders Markdown-inspired text definitions into diagrams and visualizations. It supports flowcharts, sequence diagrams, Gantt charts, class diagrams, ER diagrams, state diagrams, and more, all from plain text.

Mermaid is natively supported in GitHub Markdown, GitLab, Notion, Obsidian, and Docusaurus. It lets developers create documentation diagrams without Figma, draw.io, or any visual editor. Written in TypeScript with an MIT license.

How it saves time or tokens

Mermaid eliminates the context switch between writing documentation and creating diagrams. Instead of opening a separate tool, exporting images, and embedding them, you write diagram definitions inline with your documentation. Changes to diagrams are version-controlled alongside code. AI agents can generate and modify Mermaid diagrams as text, which is far more efficient than manipulating image files. The CLI tool renders diagrams to SVG or PNG for contexts that do not support live rendering.

How to use

1. Write Mermaid diagrams directly in GitHub Markdown:

flowchart TD

A[User visits site] --> B{Logged in?}

B -->|Yes| C[Dashboard]

B -->|No| D[Login page]

D --> E[Enter credentials]

E --> B

1. Use the CLI for rendering to files:

npm i -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg -t dark
mmdc -i input.mmd -o output.png -w 1200

1. Embed in HTML for web applications:

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true, theme: 'dark' });
</script>
<pre class="mermaid">
sequenceDiagram
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: user record
    API-->>Client: JWT token
</pre>

Example

An entity-relationship diagram for a project management system:

erDiagram
    USER ||--o{ PROJECT : owns
    PROJECT ||--|{ TASK : contains
    TASK }o--|| USER : assigned_to
    PROJECT ||--o{ MEMBER : has
    USER ||--o{ MEMBER : participates

Related on TokRepo

• Documentation tools — More documentation and diagramming tools on TokRepo.
• Coding tools — Browse developer tools for AI-assisted workflows.

Common pitfalls

• Complex diagrams with many nodes and edges become unreadable. Break large diagrams into multiple smaller ones focused on specific subsystems.
• Not all Mermaid diagram types are supported in every platform. GitHub supports flowcharts, sequence, class, state, ER, Gantt, pie, and git graphs, but some newer types may lag.
• Using Mermaid's live editor for collaboration does not save state. Export diagram definitions to your repository for version control.