If you've ever tried creating diagrams in Markdown and got stuck on the syntax, you're not alone. Mermaid is a JavaScript-based diagramming tool that lets you write diagrams using simple text and code. It's built into GitHub, GitLab, Notion, Obsidian, and many documentation platforms. But the syntax can trip up even experienced developers, especially when you move beyond basic flowcharts. A solid reference for Mermaid diagram code syntax saves you time, reduces trial and error, and helps you build accurate, readable diagrams on the first try.

What Is Mermaid Diagram Syntax Exactly?

Mermaid uses a plain-text markup language. You write code that describes the structure of a diagram nodes, connections, labels, styles and a rendering engine turns it into a visual graphic. The syntax is specific to each diagram type: flowcharts use one set of rules, sequence diagrams use another, and entity-relationship diagrams have their own conventions.

The key thing to understand is that Mermaid is declarative. You describe what the diagram looks like, not how to draw it. This makes it faster than dragging boxes in a GUI once you know the syntax.

Which Diagram Types Does Mermaid Support?

Mermaid supports a wide range of diagram types. Each one has a keyword that starts the code block:

  • flowchart (or graph) for process flows and decision trees
  • sequenceDiagram for interactions between actors or services over time
  • classDiagram for object-oriented class structures
  • erDiagram for database entity-relationship models
  • stateDiagram-v2 for state machine transitions
  • gantt for project timelines
  • pie for proportional data
  • journey for user journey maps
  • mindmap for hierarchical ideas
  • gitGraph for visualizing Git branching

You'll use most of these at some point. Flowcharts and sequence diagrams are by far the most common in day-to-day documentation work.

How Do You Write a Basic Flowchart in Mermaid?

Flowcharts are the entry point for most people. Here's the core syntax:

flowchart TD
 A[Start] --> B{Is it valid?}
 B -->|Yes| C[Process]
 B -->|No| D[Reject]
 C --> E[End]
 D --> E

A few things to notice:

  • TD means top-down. You can also use LR (left to right), BT (bottom to top), or RL.
  • Square brackets [] create rectangular nodes. Curly braces {} create diamond shapes for decisions. Round brackets () create rounded nodes.
  • Arrows (-->) connect nodes. You add labels with |text| next to the arrow.

For more complex flows with conditional logic and branching patterns, check out these flowchart diagram examples with conditional logic patterns that cover real-world decision trees and nested branches.

How Does Sequence Diagram Syntax Work?

Sequence diagrams show how different participants communicate over time. They're especially useful for documenting APIs, authentication flows, and microservice interactions.

sequenceDiagram
 participant Client
 participant Server
 participant Database

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

The arrows matter here:

  • ->> is a solid arrow (synchronous request)
  • -->> is a dashed arrow (asynchronous or return)
  • -x shows a message that fails

You can also add loops, alt blocks (if/else), and notes. If you need a head start on sequence diagram structures, this UML sequence diagram template with code examples gives you reusable patterns for common interactions.

What Does Entity-Relationship Diagram Syntax Look Like?

ER diagrams in Mermaid describe database tables and their relationships. The syntax is straightforward once you see the pattern:

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

The symbols between entities define cardinality:

  • || means exactly one
  • o{ means zero or many
  • |{ means one or many
  • o| means zero or one

For a deeper look at interactive ER diagram syntax with real schema examples, see this entity-relationship diagram code snippet guide.

What Are the Most Common Mermaid Syntax Mistakes?

After working with Mermaid for a while, you start seeing the same errors come up. Here are the ones that catch people most often:

  1. Forgetting the diagram type keyword. Every Mermaid block must start with flowchart, sequenceDiagram, erDiagram, etc. Without it, the parser doesn't know what to render.
  2. Using special characters in node labels without quotes. If your label contains parentheses, brackets, or other symbols, wrap it in quotes: A["Label (with parens)"].
  3. Wrong arrow syntax. A common mix-up is using -> instead of --> in flowcharts. The parser is strict about this.
  4. Inconsistent indentation. Mermaid doesn't care much about indentation in flowcharts, but in mindmaps and Gantt charts, indentation defines structure. Get it wrong and the diagram breaks.
  5. Missing line breaks between blocks. If you put two separate diagram types in one code block, only the first one renders. Each diagram needs its own fenced code block.
  6. Using unsupported features. Not all Mermaid features work on every platform. GitHub's Mermaid renderer, for example, has historically lagged behind the latest release. Always check which Mermaid version your platform supports.

How Do You Style Nodes and Links in Mermaid?

Mermaid gives you basic styling through classDef and style directives:

flowchart LR
 A[Normal] --> B[Important]
 B --> C[Error]

 classDef highlight fill:#f96,stroke:#333,color:#fff
 classDef error fill:#f44,stroke:#900,color:#fff

 class B highlight
 class C error

You can also apply inline styles:

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

A few notes on styling:

  • Colors use standard CSS values: hex, RGB, or named colors.
  • classDef is reusable define once, apply to multiple nodes.
  • Overuse of color makes diagrams harder to read. Use it to highlight the 2–3 things that actually matter.

Can You Add Comments and Notes in Mermaid?

Yes. Comments start with %% and don't appear in the rendered diagram:

%% This section handles auth flow
flowchart TD
 A[Login] --> B[Validate]

In sequence diagrams, you can add visible notes:

sequenceDiagram
 Alice->>Bob: Hello
 Note right of Bob: Bob thinks about it
 Bob-->>Alice: Hi back

Notes are helpful for people reading the raw source code, especially in collaborative documentation where someone might edit the diagram later.

What Are Real-World Uses for a Mermaid Syntax Reference?

You'll reach for a Mermaid reference most often when you're:

  • Writing technical documentation in Markdown for a wiki, README, or docs site
  • Planning system architecture and want a version-controllable diagram
  • Documenting API flows for backend or frontend integration
  • Modeling database schemas before writing migration scripts
  • Teaching or presenting technical concepts and need quick visuals
  • Reviewing code where a diagram would explain the logic better than comments

The advantage over tools like Lucidchart or Draw.io is that Mermaid lives in your codebase. Diagrams get reviewed in pull requests. They version naturally with Git. They're searchable as text.

What Tips Help You Write Mermaid Code Faster?

Here are practices that actually save time:

  • Use the Mermaid Live Editor to preview your diagrams while you write. It catches syntax errors immediately.
  • Start with the simplest version. Get the structure right first, then add labels, styles, and notes.
  • Reuse template patterns. Most diagrams follow a handful of shapes. Save your best ones as templates for your team.
  • Keep node IDs short. Use A, B, C for quick drafts. Switch to meaningful names like loginService only if someone else needs to read the source.
  • Watch out for long labels. They can break layouts. If a label is too long, consider abbreviating or using a note instead.
  • Test on your target platform. Syntax that works in the live editor might render differently on GitHub or Notion. Always do a final check where the diagram will actually live.

How Do You Debug a Broken Mermaid Diagram?

When a diagram won't render, follow this process:

  1. Check the first line. Is the diagram type keyword correct and spelled right?
  2. Look for unmatched brackets. Every [ needs a ], every { needs a }.
  3. Remove special characters from labels. Strip everything back to plain text, then add characters one at a time.
  4. Simplify the diagram. Comment out half the nodes and connections. When the remaining half renders, you know the bug is in the commented-out section.
  5. Check for reserved keywords. Words like end, subgraph, and style can conflict with your node IDs if you're not careful.

Most rendering errors come down to one misplaced bracket or a typo in the first line.

Practical Checklist Before You Ship a Mermaid Diagram

  • ☑ Diagram type keyword is correct and on the first line
  • ☑ All node connections use the right arrow syntax (-->, ->>, etc.)
  • ☑ Labels with special characters are wrapped in quotes
  • ☑ Indentation is correct (critical for mindmaps and Gantt charts)
  • ☑ Styles and classes are tested in the live editor or target platform
  • ☑ The diagram renders cleanly at different widths
  • ☑ A teammate can read the raw source and understand the structure

Keep this list next to your editor. Run through it every time before committing a diagram. It takes 30 seconds and prevents the most common issues from reaching your documentation.