If you've ever needed to create a flowchart, sequence diagram, or architecture overview without dragging and dropping boxes in a clunky UI, Mermaid might already be on your radar. It lets you write diagrams using plain text syntax, which means your diagrams live right alongside your code and documentation. But the syntax can trip you up fast wrong indentation, missing arrows, or an unexpected keyword can break your whole diagram. This reference covers the Mermaid diagram syntax you'll actually use, with examples you can copy and adapt right now.

What Is Mermaid Diagram Syntax?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from a text-based description language. Instead of manually drawing shapes and connecting lines, you write simple markup that Mermaid parses into visual diagrams. The syntax resembles a lightweight scripting language keywords define diagram types, arrows define relationships, and indentation or brackets group elements.

You'll find Mermaid supported in GitHub Markdown, GitLab, Notion, Obsidian, Confluence, and many documentation platforms. If you're comparing it against other options, our breakdown of diagram markup languages for software architecture covers where Mermaid fits alongside alternatives like PlantUML.

How Do You Write a Basic Flowchart in Mermaid?

Flowcharts are the most common diagram type in Mermaid. The syntax starts with the flowchart keyword (or the older graph alias) followed by a direction, then node definitions and connections.

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

Key things to know:

  • Direction keywords: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
  • Node shapes: [text] for rectangles, {text} for diamonds, (text) for rounded rectangles, ((text)) for circles, [/text/] for parallelograms
  • Arrow types: --> for solid arrows, --- for lines without arrowheads, -.-> for dotted arrows, ==> for thick arrows
  • Link labels: Add text between pipes, like |Yes| or |No|

How Does the Mermaid Sequence Diagram Syntax Work?

Sequence diagrams show interactions between participants over time. They're useful for documenting API flows, authentication processes, or any multi-step communication between systems.

sequenceDiagram
 participant Client
 participant Server
 participant Database
 
 Client->>Server: POST /login
 Server->>Database: Query user
 Database-->>Server: User data
 Server-->>Client: 200 OK + token

Important syntax details:

  • ->> creates a solid arrow with an open arrowhead (synchronous message)
  • -->>> creates a dashed arrow with an open arrowhead (asynchronous message)
  • --> and -->> create dashed lines (return/response messages)
  • Activation boxes: Use activate ParticipantName and deactivate ParticipantName to show processing time
  • Notes: Note right of Server: Processing request or Note over Client,Server: TLS handshake
  • Loops and conditions: loop Every 30 seconds, alt Success / else Failure, opt Optional step

If you want to compare Mermaid's sequence syntax with another popular tool, check out our PlantUML sequence diagram cheat sheet the conceptual structure is similar, but the syntax differs.

How Do You Create a Class Diagram with Mermaid?

Class diagrams model object-oriented structures. Mermaid's syntax uses curly braces to define attributes and methods inside classes.

classDiagram
 class User {
 +String name
 +String email
 +login()
 +logout()
 }
 class Order {
 +String orderId
 +Date createdAt
 +calculateTotal()
 }
 User "1" --> "" Order : places

Symbols matter here: + means public, - means private, # means protected, ~ means package-private. Relationship arrows include --> (association), -- (composition), o-- (aggregation), and --|> (inheritance).

What's the Syntax for Mermaid State Diagrams?

State diagrams track how an object transitions between states. They use the stateDiagram-v2 keyword.

stateDiagram-v2
 [] --> Idle
 Idle --> Processing : submit
 Processing --> Success : approved
 Processing --> Failed : error
 Failed --> Idle : retry
 Success --> []

The [] symbol represents the start and end states. You can also nest states for substates using curly braces, which helps model complex workflows like multi-phase approvals.

How Do You Draw an ER Diagram in Mermaid?

Entity-relationship diagrams document database schemas. Mermaid's ER diagram syntax uses erDiagram and defines relationships with cardinality markers.

erDiagram
 CUSTOMER ||--o{ ORDER : places
 ORDER ||--|{ LINE_ITEM : contains
 CUSTOMER {
 string name
 string email
 }
 ORDER {
 int order_id
 date created_at
 string status
 }

Cardinality symbols: || means exactly one, |o means zero or one, }| means one or many, }o means zero or many. The notation reads left to right, so CUSTOMER ||--o{ ORDER means "one customer places zero or many orders."

What About Mermaid Gantt Chart and Pie Chart Syntax?

Mermaid supports project timelines and data visualizations too.

Gantt charts use sections and task definitions:

gantt
 title Project Timeline
 dateFormat YYYY-MM-DD
 section Design
 Wireframes :a1, 2024-01-01, 14d
 Prototypes :a2, after a1, 10d
 section Development
 Frontend :b1, after a2, 21d
 Backend :b2, after a2, 28d

Pie charts are simpler:

pie title Bug Distribution
 "Frontend" : 40
 "Backend" : 35
 "Infrastructure" : 25

What Are the Most Common Mermaid Syntax Mistakes?

These errors come up constantly, especially when you're starting out:

  • Missing or wrong direction keyword: Every flowchart needs flowchart TD or similar. Without it, Mermaid won't render.
  • Unquoted special characters in node text: If your label contains parentheses, brackets, or other special characters, wrap it in quotes: A["Text with (parens)"]
  • Wrong arrow syntax for diagram type: Sequence diagrams use ->>, while flowcharts use -->. Mixing them up produces broken output.
  • Indentation issues in nested structures: Loops, alts, and substates depend on correct indentation. One wrong space can shift the whole structure.
  • Forgetting the diagram type declaration: Every Mermaid diagram must start with its type keyword flowchart, sequenceDiagram, classDiagram, erDiagram, etc.
  • Using node IDs that collide with keywords: Avoid naming nodes end, start, or subgraph without quotes, as they're reserved terms.

How Do You Add Styling and Themes to Mermaid Diagrams?

Mermaid supports inline styling through the style keyword and classDef for reusable classes:

flowchart TD
 A[Start] --> B[Process] --> C[End]
 
 classDef highlight fill:#f96,stroke:#333,stroke-width:2px
 class B highlight

You can also apply themes globally by configuring the theme setting. Available built-in themes are default, forest, dark, and neutral. The official Mermaid theming documentation covers custom theme variables in detail.

Where Can You Test Mermaid Diagram Syntax?

You don't need to set up a project to test your syntax. The Mermaid Live Editor lets you write syntax on the left and see the rendered diagram on the right in real time. It's the fastest way to debug broken diagrams or experiment with new diagram types.

Other places to test:

  • GitHub README files and issues (Mermaid renders natively)
  • VS Code with the Mermaid extension
  • Obsidian, Notion, and Confluence (all support Mermaid blocks)

Our full Mermaid diagram syntax reference covers additional diagram types like mind maps, timelines, and quadrant charts that have been added in recent versions.

Practical Checklist: Quick Reference for Mermaid Syntax

  • Start every diagram with its type keyword (flowchart TD, sequenceDiagram, classDiagram, etc.)
  • Use --> for flowchart connections and ->> for sequence diagram messages
  • Wrap labels with special characters in double quotes
  • Test syntax in the Mermaid Live Editor before committing to docs
  • Use subgraph to group related nodes in flowcharts
  • Keep diagrams small one diagram per concept is easier to maintain than one large diagram
  • Check your Mermaid version some features require v10+
  • Pin diagram versions in production documentation, since rendering can vary between Mermaid releases

Start by writing one diagram for a workflow you explain often. Put it in a README or your team wiki. You'll learn the syntax fastest by fixing what breaks in real usage, not by memorizing the full reference upfront.