JavaScript-based diagramming tool that generates diagrams from Markdown-inspired text definitions. Supports 30+ diagram types including flowcharts, sequence diagrams, Gantt charts, class diagrams, ER diagrams, and mindmaps. Use when creating visual diagrams from text in documentation, markdown files, HTML pages, or any environment supporting Mermaid rendering via CDN or npm.
JavaScript-based diagramming tool that generates diagrams from Markdown-inspired text definitions. Supports 30+ diagram types including flowcharts, sequence diagrams, Gantt charts, class diagrams, ER diagrams, and mindmaps. Use when creating visual diagrams from text in documentation, markdown files, HTML pages, or any environment supporting Mermaid rendering via CDN or npm.
Mermaid is a JavaScript-based diagramming and charting tool that renders diagrams
from Markdown-inspired text definitions. It addresses the "Doc-Rot" problem by
enabling easily modifiable diagrams that can be made part of production scripts
and documentation workflows. Diagrams are rendered as SVG in the browser, with
optional PNG export.
Mermaid 11.14.0 is the current stable release on npm. It supports over 28 diagram
types, multiple themes, frontmatter configuration, layout algorithm selection
(dagre/ELK), visual looks (classic/handDrawn), and integrates natively with
GitHub, GitLab, Obsidian, VS Code, and many other platforms via markdown code
fences.
When to Use
Creating diagrams inline in Markdown documentation (GitHub, GitLab, Notion, Obsidian)
Generating flowcharts, sequence diagrams, Gantt charts, or class diagrams from text
Embedding diagrams in HTML pages via CDN or npm package
Building visual documentation that stays in sync with code
Prototyping system architecture, ER models, or user journey maps
Creating project timelines, git branching visualizations, or mindmaps
Core Concepts
Mermaid is composed of three parts:
Deployment — How Mermaid is loaded and rendered (Live Editor, CDN, npm, plugins)
Syntax — The Markdown-inspired text definitions for each diagram type
Every diagram definition begins with a declaration of the diagram type keyword
(e.g., flowchart, sequenceDiagram, gantt), followed by the diagram content.
Line comments use %% prefix.
ZenUML (zenuml) — alternative sequence diagram syntax
Frontmatter Configuration
Mermaid supports YAML frontmatter for per-diagram configuration:
---
title: My Diagram
config:
theme: forest
layout: elk
look: handDrawn
---
flowchart LR
A --> B
Themes
Five built-in themes: default, neutral, dark, forest, base.
Only base is customizable via themeVariables.
Layout Algorithms
dagre (default) — classic layout, good balance of simplicity and clarity
elk — advanced Eclipse Layout Kernel for complex diagrams (requires separate loading)
Visual Looks
classic — the original Mermaid appearance
handDrawn — sketch-like, informal style
Usage Examples
Inline in Markdown (GitHub, GitLab, Obsidian)
Wrap diagram code in a mermaid fenced code block:
```mermaid
flowchart LR
A[Start] --> B{Decision}
B -->|Yes| C[Continue]
B -->|No| D[Stop]
```
HTML Page via CDN
<!doctype html><html><body><preclass="mermaid">
graph LR
A --> B --> C
</pre><scripttype="module">import mermaid from'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script></body></html>
Simple Flowchart
flowchart TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
Sequence Diagram
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!
Gantt Chart
gantt
title Project Schedule
dateFormat YYYY-MM-DD
section Development
Design :done, des1, 2024-01-01, 7d
Develop :active, des2, after des1, 14d
Testing : des3, after des2, 10d
