Only One Final Page Title

If you've ever stared at a blank editor trying to remember how to start a sequence diagram or forgot whether it's --> or -->> for a message arrow, you know exactly why a mermaid diagram syntax cheatsheet is worth bookmarking. Mermaid.js lets you write diagrams using simple text, but the syntax varies between diagram types and that's where a quick-reference sheet saves you real time.

What Exactly Is a Mermaid Diagram Syntax Cheatsheet?

A cheatsheet for Mermaid diagram syntax is a condensed reference that shows the most common diagram types and their code patterns in one place. Instead of digging through full documentation every time you need to draw a flowchart, sequence diagram, or Gantt chart, you glance at the sheet and get back to writing.

Mermaid is an open-source JavaScript library that renders diagrams from text-based definitions. It works inside Markdown files, GitHub README files, documentation sites, and many code editors. You write a few lines of structured text, and Mermaid turns that into a visual diagram. You can read more about the full Mermaid Markdown diagramming syntax for deeper context.

Who Needs This and When?

Developers writing technical documentation, project managers mapping out workflows, and technical writers building knowledge bases all reach for a Mermaid cheatsheet regularly. Common situations include:

Writing a GitHub issue or pull request that needs a quick diagram
Documenting a system architecture in a README file
Planning a database schema visually before writing SQL
Creating process flows during sprint planning or design reviews

Because Mermaid diagrams live inside plain text, they're version-controlled alongside your code. That alone makes them more practical than screenshots or drag-and-drop tools for many teams.

Core Diagram Types and Their Syntax

Flowcharts

Flowcharts are the most common Mermaid diagram. The keyword graph or flowchart starts the definition. Nodes are defined by their shape square brackets for rectangles, parentheses for rounded boxes, and curly braces for diamonds.

graph TD
 A[Start] --> B{Is it working?}
 B -->|Yes| C[Great]
 B -->|No| D[Fix it]
 D --> B

TD means top-down. Use LR for left-to-right. If you want a detailed walkthrough, our guide on creating flowcharts with Mermaid code covers node types and styling in depth.

Sequence Diagrams

Sequence diagrams show interactions between actors or objects over time. They use sequenceDiagram as the opening keyword.

sequenceDiagram
 participant User
 participant Server
 participant Database
 User->>Server: Send login request
 Server->>Database: Query user
 Database-->>Server: Return user data
 Server-->>User: Login success

Double arrows (-->> ) represent dashed lines, commonly used for return messages. Solid arrows (>) represent requests or calls.

Class Diagrams

For object-oriented designs, class diagrams use classDiagram as the keyword. You define classes, attributes, methods, and relationships.

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

State Diagrams

State diagrams model how an object changes between states. They start with stateDiagram-v2.

stateDiagram-v2
 [] --> Idle
 Idle --> Processing: submit
 Processing --> Done: complete
 Processing --> Error: fail
 Error --> Idle: retry
 Done --> []

Gantt Charts

Gantt charts for project timelines use the gantt keyword and define tasks with start dates, durations, and dependencies.

gantt
 title Project Plan
 dateFormat YYYY-MM-DD
 section Design
 Wireframes :done, des1, 2024-01-01, 7d
 UI Mockups :active, des2, after des1, 5d
 section Development
 Frontend : dev1, after des2, 10d
 Backend : dev2, after des2, 12d

Pie Charts

Simple data visualization uses the pie keyword.

pie title Bug Distribution
 "Frontend" : 35
 "Backend" : 45
 "DevOps" : 20

Entity Relationship Diagrams

ER diagrams model database relationships using erDiagram.

erDiagram
 CUSTOMER ||--o{ ORDER : places
 ORDER ||--|{ LINE_ITEM : contains
 CUSTOMER {
 int id PK
 string name
 string email
 }

Common Syntax Mistakes People Make

Missing the diagram keyword on line one. Every Mermaid diagram must start with a recognized keyword like graph, sequenceDiagram, or classDiagram. Without it, nothing renders.
Wrong arrow syntax between diagram types. Flowcharts use -->, but sequence diagrams need > or -->> . Mixing them up silently fails.
Forgetting indentation. Mermaid is sensitive to whitespace in some diagram types. Gantt chart task definitions, for example, won't parse without proper indentation under a section.
Special characters in node text. If your label contains parentheses or brackets, wrap the entire text in double quotes: A["Start (phase 1)"].
Using deprecated syntax. The older stateDiagram keyword (without -v2) has limited features. Always use stateDiagram-v2 for state diagrams.

Tips That Make Working with Mermaid Easier

Test small and build up. Write two or three nodes first, confirm they render, then add complexity. Debugging a 50-line diagram from scratch is frustrating.
Use the live editor. The Mermaid Live Editor shows a real-time preview of your diagram. Paste your code there to catch syntax errors fast.
Name your nodes explicitly. Instead of relying on auto-generated IDs like A, B, C, use descriptive names like LoginPage or ValidateInput. It keeps diagrams readable when you revisit them weeks later.
Add comments with %%. Double percent signs create comments in Mermaid code. Use them to explain non-obvious sections for teammates.
Style with CSS classes. Mermaid supports classDef for defining reusable styles and class for applying them. This keeps your diagram colors consistent without inline styles.

For a broader overview covering all supported diagram types, our complete Mermaid syntax cheatsheet has every keyword and pattern listed out.

Where Mermaid Diagrams Actually Work

Mermaid rendering is supported in many tools you may already use:

GitHub Mermaid code blocks in Markdown files and issues render automatically since 2022.
GitLab Supported in Markdown files, wikis, and issues.
Notion Use the Mermaid code block type to embed diagrams in pages.
VS Code Extensions like "Mermaid Markdown Syntax Highlighting" and "Markdown Preview Mermaid Support" add live preview.
Obsidian Native Mermaid support inside Markdown notes.
Confluence Available through marketplace apps that embed Mermaid rendering.

Check the official Mermaid.js documentation for the latest list of integrations and version updates.

Quick-Reference Checklist

Before you share or commit a Mermaid diagram, run through this:

Does the first line contain a valid diagram keyword?
Are all arrows using the correct syntax for the diagram type?
Do node labels with special characters use double quotes?
Did you preview it in the Mermaid Live Editor or your editor's preview pane?
Are node names descriptive enough for someone else to understand?
Is indentation consistent throughout the diagram definition?
Have you added comments (%%) for any non-obvious logic?
If using Gantt or class diagrams, did you check for the most current syntax (e.g., stateDiagram-v2)?

Print this list or keep it next to your cheatsheet. The syntax gets easier with practice, but even experienced users forget arrow formats across diagram types. A reliable reference combined with the live editor for quick testing means you spend less time debugging markup and more time communicating ideas clearly.