Mermaid 11 15 0

Mermaid 11.15.0

Overview

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions into SVG diagrams. It supports 29 diagram types covering flowcharts, UML diagrams, data visualizations, architecture diagrams, and more. Diagrams are defined as plain text, making them version-controllable, easily editable, and embeddable in any markdown-based documentation.

When to Use

• Creating diagrams inline in Markdown files (GitHub, GitLab, Obsidian, Notion)
• Generating flowcharts, sequence diagrams, ER diagrams, Gantt charts, class diagrams, or state diagrams from text
• Embedding diagrams in web pages via CDN or npm package
• Producing visualizations for documentation that must stay in sync with code
• Building interactive diagrams with click events and tooltips
• Creating architecture diagrams (C4, block, wardley, event modeling)
• Visualizing git branching strategies

Core Concepts

Diagram Declaration

Every diagram begins with a keyword declaring its type:

flowchart LR
    A --> B

The keyword (flowchart, sequenceDiagram, gantt, etc.) tells the parser which renderer to use. Use graph as an alias for flowchart.

Frontmatter Configuration (v10.5.0+)

Override configuration per-diagram using YAML frontmatter:

---
title: My Diagram
config:
  theme: forest
  layout: elk
---
flowchart LR
    A --> B

Frontmatter replaces the older %%{init: {...}}%% directive syntax (deprecated).

Comments and Accessibility

• Line comments: %% this is a comment
• Accessible title: accTitle: Short descriptive title
• Accessible description: accDescr: Single line description.
• Multi-line description uses { ... } without colon

Direction Keywords

Special Syntax Rules

• The word end breaks flowcharts and sequence diagrams — capitalize it (End) or quote it
• Use double quotes for text with special characters: id["text (with) parens"]
• Markdown strings use backticks: id["\**bold** and *italic*`"]`
• Entity codes escape characters: #quot;, #35;

Quick Start

In Markdown (GitHub, GitLab, Obsidian)

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

On a Web Page (CDN)

<pre class="mermaid">
flowchart LR
    A --> B
</pre>
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

As npm Dependency

npm install mermaid

import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: false });
const { svg } = await mermaid.render('myDiagram', 'flowchart LR\nA --> B');
element.innerHTML = svg;

Key API Methods

• mermaid.initialize(config) — set site-wide configuration (call once)
• mermaid.render(id, text) — render diagram to SVG
• mermaid.run(options) — render diagrams by selector or node array (v10+)
• mermaid.detectType(text) — detect diagram type from text
• mermaid.parse(text, options) — validate syntax without rendering

Advanced Topics

Getting Started and Deployment

Installation, CDN, npm, API usage, security levels, mermaid.run, Tiny Mermaid → Getting Started

Configuration

Frontmatter config, initialize(), directives (legacy), parse(), render(), detectType() → Configuration

Theming

5 built-in themes, themeVariables customization, per-diagram and site-wide theming, color derivation → Theming

Accessibility

accTitle, accDescr (single/multi-line), aria-roledescription, aria-labelledby examples for all diagram types → Accessibility

Layouts, Icons, Math, CLI

Layout engines (dagre, elk, tidy-tree, cose-bilkent), icon packs, KaTeX math rendering, tidy-tree, mermaid CLI → Layouts and Icons

Diagram Types