How to use Mermaid

Education · Updated March 2026

What Mermaid is (and why teams use it)

Mermaid is a text-to-diagram open-source language: you write a definition, a renderer produces SVG. Text plays nicely with Git and code review—unlike stale binary diagrams. The canonical syntax reference is the mermaid.js.org site.

What you need before you start

• Use the live editor above on this page (same features as the standalone Mermaid tool: preview, themes, SVG/PNG, share, snapshots).
• From /mermaid or the toolkit landing, the toolbar Guide button returns here.
• Patience with parse errors: Mermaid is strict; fix one line at a time when the preview complains.

Step 1 — Your first flowchart

Flowcharts describe decisions and order. In Mermaid you declare the diagram type, then nodes and edges. A minimal left-to-right example (the same shape as the official quick-start style) looks like this:

flowchart LR
    A[Start] --> B{Valid?}
    B -->|Yes| C[Continue]
    B -->|No| D[Fix]
    D --> B

flowchart LR sets direction (left-right). --> draws a solid arrow. Braces { } mark a diamond decision. Text after a pipe on an edge, like |Yes|, labels that branch. Try changing labels, adding another node, or switching to flowchart TD for top-down layout. The live editor debounces rendering so the preview updates shortly after you pause typing.

Shapes and connectors match the official flowchart docs (e.g. [Label], A --> B --> C, or --- for undirected lines).

Step 2 — Sequence diagrams for APIs and UX

Declare sequenceDiagram, name participants, then ->> / -->> for request and reply—see mermaid.js.org for alt, loop, and notes. In the editor, More → Sequence inserts a starter template.

Step 3 — State diagrams for modes and lifecycles

Use stateDiagram-v2 and transitions like Idle --> Running : start; add nesting when readers need it (official state docs). More → State drops in a skeleton.

Step 4 — Themes, export, and sharing in the editor

More exposes default, dark, and forest themes (saved with your source locally). SVG exports the last good render; PNG rasterizes at 2× on white—prefer SVG for very large graphs. Share copies an encoded link (short links may prompt consent). Save is for named local snapshots only.

Syntax habits that keep you out of trouble

• One top-level diagram keyword per definition.
• Match quotes and brackets; typos surface as parser errors in the preview.
• For class, ER, Gantt, pie, and other types, confirm keywords against your Mermaid version on mermaid.js.org.

Next steps

Keep iterating in the editor above, open the full-screen editor for a minimal chrome layout, skim /tools/mermaid-diagram-editor, and draft prose with the Markdown notes tool when you ship READMEs or runbooks.

Frequently asked questions

Do I need to install Mermaid to follow this guide?

No. This page includes the full live editor and preview above the article—paste examples and watch the diagram update. Installation is only required if you embed Mermaid in your own build pipeline or static site generator.

Where is the official syntax reference?

The Mermaid project maintains authoritative documentation at mermaid.js.org, including every diagram type, configuration option, and migration note. Use it when this guide does not cover an edge case.

Why does my diagram show an error in the preview?

Usually a typo, wrong diagram keyword, or a feature not supported by the Mermaid version bundled in the app. Read the error text in the preview, compare with the official docs, and fix the line it points to.

Can I use Mermaid in GitHub or GitLab Markdown?

Many platforms render fenced code blocks tagged as mermaid automatically. Syntax is the same as in our editor; always verify rendering on the target platform because supported types and versions can differ.