Mermaid Diagram Syntax Reference Guide

Mermaid is a JavaScript-based diagramming tool that lets you create flowcharts, sequence diagrams, Gantt charts, and more using plain text. Instead of dragging shapes around in a visual editor, you write simple code, and Mermaid renders it into a clean diagram. If you've ever needed to document a system, explain a process, or visualize data inside a Markdown file, knowing Mermaid syntax saves you real time. This reference guide covers every major diagram type, the exact syntax you need, common pitfalls, and practical examples you can copy and start using right away.

What is Mermaid diagram syntax, and how does it work?

Mermaid uses a lightweight markup language. You write structured text that describes nodes, connections, labels, and directions. A Mermaid parser then converts that text into SVG diagrams. The syntax reads almost like pseudocode it's designed to be written and read by humans, not just machines.

A basic Mermaid block starts with a keyword that declares the diagram type (like flowchart, sequenceDiagram, or classDiagram), followed by the body that defines elements and relationships. Here's a minimal example:

flowchart TD
A[Start] --> B[End]

This creates a simple top-down flowchart with two nodes and one arrow connecting them. From here, the syntax scales to handle complex diagrams with styling, subgraphs, conditions, and more.

When should you use Mermaid instead of a visual diagram tool?

Mermaid makes the most sense in these situations:

You're writing documentation inside Markdown files, wikis, or README files
You want diagrams that live alongside your code in version control
You need to update diagrams frequently without rebuilding them manually
You use platforms that support Mermaid natively, like GitHub, GitLab, Notion, Obsidian, or Confluence with plugins
You prefer text-based tools and want to avoid switching to a separate visual editor

For quick wireframes or highly visual presentations, a drag-and-drop tool might still be better. But for documentation that needs to stay maintainable and trackable, Mermaid is hard to beat.

How do you write a flowchart in Mermaid?

Flowcharts are the most common Mermaid diagram. They use the flowchart keyword (or the older graph keyword) and define nodes and links between them.

flowchart LR
  A[User submits form] --> B{Valid data?}
  B -->|Yes| C[Save to database]
  B -->|No| D[Show error message]
  C --> E[Send confirmation email]

Key syntax elements for flowcharts:

Direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
Node shapes: [text] for rectangles, (text) for rounded, {text} for diamonds, [[text]] for subroutines, [(text)] for cylinders/databases
Links: --> for arrows, --- for lines without arrowheads, -.-> for dotted arrows
Link labels: |text| placed after the arrow
Subgraphs: Use subgraph name and end to group related nodes

If you're just getting started with flowchart markup, our flowchart markup quick-start guide walks through the basics step by step.

How do you build a sequence diagram?

Sequence diagrams show interactions between actors or components over time. They're useful for documenting API calls, authentication flows, or any process where the order of messages matters.

sequenceDiagram
  participant User
  participant App
  participant Server
  User->>App: Click login
  App->>Server: POST /auth
  Server-->>App: 200 OK + token
  App-->>User: Show dashboard

Important syntax points:

Arrows: ->> for solid arrows, -->> for dashed arrows (responses)
Activations: activate Actor and deactivate Actor to show processing time
Notes: Note left of Actor: text or Note over Actor1,Actor2: text
Loops and conditions: loop, alt, else, and end blocks
Parallel actions: par blocks for concurrent processes

For more advanced sequence diagram patterns, check out these sequence diagram code examples that cover real-world interaction patterns.

How do you create a class diagram?

Class diagrams model object-oriented structures. Mermaid supports attributes, methods, visibility modifiers, and relationships like inheritance, composition, and association.

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound() void
  }
  class Dog {
    +fetch() void
  }
  Animal <|-- Dog

Visibility markers: + for public, - for private, # for protected, ~ for package/internal.

Relationship lines:

<|-- inheritance
-- composition
o-- aggregation
--> association
..> dependency

You can also add multiplicity with annotations like "1" --> "many" and stereotype labels with <<interface>> or <<abstract>>.

What other diagram types does Mermaid support?

Beyond flowcharts, sequence diagrams, and class diagrams, Mermaid handles several more:

State diagrams: Model state machines with stateDiagram-v2
Entity-relationship diagrams: Define database schemas with erDiagram
Gantt charts: Project timelines with gantt
Pie charts: Data visualization with pie
User journey maps: Customer experience flows with journey
Git graphs: Branch and commit visualization with gitGraph
Mindmaps: Hierarchical ideas with mindmap
Quadrant charts: Four-quadrant data plots with quadrantChart

Each diagram type has its own keyword and its own set of sub-commands, but the overall structure declare the type, then define elements stays consistent across all of them. If you need a broader cheat sheet covering multiple diagram languages, our UML diagram scripting cheat sheet compares syntax across tools.

How do you add styling and themes to Mermaid diagrams?

Mermaid supports inline styles using the style keyword and CSS-like properties:

style A fill:#f9f,stroke:#333,stroke-width:2px

You can also define reusable classes with classDef:

classDef success fill:#d4edda,stroke:#28a745
class A,B success

For broader theming, Mermaid's %%{init: {'theme': 'dark'}}%% directive at the top of your diagram applies preset themes like default, forest, dark, neutral, and base. Custom theme variables let you control colors for backgrounds, lines, text, and more at a global level.

What are the most common Mermaid syntax mistakes?

Even though Mermaid's syntax is straightforward, these errors come up frequently:

Missing direction in flowcharts. Forgetting TD or LR after flowchart causes render failures. Always declare direction.
Special characters in node text. Parentheses, brackets, and quotes inside labels need to be wrapped in quotes: A["Text with (parentheses)"]
Wrong arrow syntax for the diagram type. Flowcharts use -->, sequence diagrams use ->>. Mixing them up breaks rendering.
Forgetting end keywords. Subgraphs, loops, and conditional blocks all need a closing end.
Indentation issues. Mermaid is somewhat forgiving, but nested blocks (subgraphs, loops) render better with consistent indentation.
Using HTML tags without quotes. If you include <br> or other HTML in labels, wrap the label in quotes.

The quickest way to debug syntax issues is to use the Mermaid Live Editor, which shows errors in real time as you type.

Where does Mermaid diagram syntax work natively?

You don't always need a separate tool. These platforms render Mermaid blocks automatically:

GitHub: Markdown files and issues render Mermaid in fenced code blocks tagged with mermaid
GitLab: Supports Mermaid in Markdown with the same fenced block syntax
Notion: /mermaid command or code blocks with Mermaid syntax
Obsidian: Fenced code blocks render inline with the Mermaid diagram support
Confluence: Via marketplace plugins
VS Code: With the Mermaid extension for previewing diagrams
Slack and Teams: Via third-party apps or bots

How do you embed Mermaid diagrams in a web page?

There are two main approaches:

Client-side rendering with the Mermaid JS library:

Include the Mermaid script from a CDN, then place your diagram inside a div with class mermaid. The library parses and renders diagrams on page load. This is simple but adds a dependency to your page.

Pre-rendered SVG:

Use the Mermaid CLI (@mermaid-js/mermaid-cli) to generate SVG files during your build process. Then embed the SVG directly in your HTML. This approach is faster for page load and avoids runtime JavaScript, which is better for static sites and documentation pages like this one.

What are some practical tips for writing cleaner Mermaid code?

Keep node IDs short. Use A, B, step1 as IDs, and put the long display text inside the brackets.
Use subgraphs to organize complexity. Grouping related nodes makes diagrams readable and layout more predictable.
Add link labels generously. Unlabeled arrows in complex diagrams confuse readers.
Comment your code. Use %% for comments to explain non-obvious sections.
Test in the live editor first. Before committing to your documentation, verify rendering at mermaid.live.
Version your diagrams alongside code. Since Mermaid is plain text, it works naturally in Git workflows.

Quick reference checklist for your next Mermaid diagram

Use this checklist every time you write a new diagram:

✅ Pick the right diagram type for your use case (flowchart, sequence, class, state, ER, etc.)
✅ Declare the diagram keyword and direction/type first
✅ Use short IDs and descriptive display labels for nodes
✅ Double-check arrow syntax matches the diagram type
✅ Close every subgraph, loop, and conditional block with end
✅ Escape special characters in labels with quotes
✅ Test rendering in the Mermaid Live Editor before committing
✅ Use classDef and style for consistent visual styling
✅ Add comments for complex or non-obvious sections
✅ Keep diagrams focused split large diagrams into smaller linked ones when possible

Start with a simple diagram today. Pick one process or system you've been meaning to document, write it out in ten lines of Mermaid syntax, and see how fast it renders. You'll have a working diagram in under five minutes.