If you've ever needed to explain a process, map out a decision tree, or document a system workflow without dragging boxes around in a clunky diagram tool, Mermaid flowchart syntax gives you a fast, text-based way to do it. You write simple code, and a diagram appears. This reference guide walks you through the syntax piece by piece so you can build flowcharts quickly and avoid the frustrating trial-and-error that trips up most beginners.

What exactly is Mermaid flowchart syntax?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from plain text. The flowchart keyword is one of its most used diagram types. Instead of opening a visual editor, you write short lines of code that describe nodes (shapes) and links (arrows between them). Mermaid then converts that code into an SVG diagram.

Mermaid runs inside markdown editors, documentation platforms, and web apps. GitHub, GitLab, Notion, Obsidian, and many other tools support it natively. You can also use the Mermaid Live Editor to test syntax in your browser without installing anything.

If you're comparing different code-based diagramming approaches, our tools comparison for flowchart code scripts covers several alternatives alongside Mermaid.

How do you write a basic Mermaid flowchart?

Every Mermaid flowchart starts with the flowchart keyword (or graph, which works the same way). You pick a direction, then define nodes and connections.

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

Here's what each part means:

  • TD means "top down." Other options are LR (left to right), BT (bottom to top), and RL (right to left).
  • A[Start] creates a node with ID A and the label "Start." Square brackets make a rectangle.
  • --> draws an arrow. -->|Yes| adds a label to the arrow.
  • B{Is it working?} creates a diamond shape (decision node) because of the curly braces.

What node shapes can you use?

Mermaid gives you several shapes based on the bracket type you wrap around the label. This is the part most people need to look up repeatedly:

  • A[text] Rectangle (standard process box)
  • A(text) Rounded rectangle (stadium/rounded)
  • A{text} Diamond (decision)
  • A{{text}} Hexagon
  • A[[text]] Subroutine shape (double-bordered rectangle)
  • A[(text)] Cylinder (database)
  • A((text)) Circle
  • A>text] Flag/asymmetric shape
  • A[/text/] Parallelogram
  • A[\text\] Parallelogram (alternate tilt)
  • A[/text\] Trapezoid
  • A[\text/] Trapezoid (alternate)

You can also mix bracket types. For example, A([text]) gives you an extended rounded shape (like a stadium with more curve). Play around in the live editor to see the differences there's no substitute for seeing these rendered.

How do you connect nodes with different arrow types?

Connection syntax determines the line style and arrowhead between nodes. Here are the main options:

  • A --> B Arrow with arrowhead
  • A --- B Line with no arrowhead
  • A -->|label| B Arrow with text label
  • A -.-> B Dotted arrow
  • A -.->|label| B Dotted arrow with label
  • A ==> B Thick arrow
  • A ==>|label| B Thick arrow with label
  • A ~~~ B Invisible link (useful for layout control)

You can also define a connection and label the destination node on the same line:

flowchart LR
 A --> B[New Label]
 A --> C[Another Label]

How do you handle subgraphs and grouping?

When your flowchart grows, subgraphs let you group related nodes inside a labeled container. This keeps complex diagrams organized and readable.

flowchart TD
 A[Receive Order] --> B[Process Payment]
 
 subgraph Inventory [Inventory Management]
 C[Check Stock]
 D[Reserve Item]
 end
 
 B --> C
 C --> D
 D --> E[Ship Order]

You can change the flow direction inside a subgraph independently from the parent chart. Just add a direction keyword after the subgraph label: subgraph Inventory [Inventory Management] and then a new line with direction LR.

Subgraphs are especially helpful when you're building process documentation that covers multiple systems or departments. If you're generating these diagrams programmatically with code, our guide on Python libraries for generating flowchart scripts shows how to build and output Mermaid syntax from data.

How do you add styling and classes to nodes?

Default Mermaid diagrams work fine, but you can style individual nodes or define reusable classes. This matters when you need color coding for status indicators, error states, or approval paths.

flowchart TD
 A[Start] --> B[Review]
 B --> C[Approved]
 B --> D[Rejected]
 
 style A fill:#e0f0ff,stroke:#333
 style C fill:#d4edda,stroke:#28a745
 style D fill:#f8d7da,stroke:#dc3545

For reusable styling, define a class and apply it to multiple nodes:

classDef success fill:#d4edda,stroke:#28a745,color:#000
classDef error fill:#f8d7da,stroke:#dc3545,color:#000

class C success
class D error

What common mistakes break Mermaid flowcharts?

Mermaid's parser is strict about syntax. Here are the errors people hit most often:

  1. Special characters in labels. Parentheses, quotes, and brackets inside labels confuse the parser. Wrap problematic labels in quotes: A["Label with (parentheses)"].
  2. Missing direction keyword. Forgetting TD or LR after flowchart will throw an error. Always declare a direction.
  3. Inconsistent node IDs. If you define MyNode as a rectangle but later reference it as a diamond with different brackets, the second definition is ignored. Pick one shape per node ID.
  4. Indentation inside subgraphs. Mermaid doesn't require specific indentation, but mixing tabs and spaces inconsistently can cause rendering issues in some parsers.
  5. Missing end keyword. Every subgraph block must close with end. Forgetting this is the most common subgraph error.
  6. Unescaped characters in link labels. Use quotes around labels that contain pipes, arrows, or other syntax characters: A -->|"Step 1 → Step 2"| B.

How do you create clickable links in Mermaid flowcharts?

Mermaid supports interactive nodes that link to URLs. This works when the rendered output supports interactivity (the live editor, GitLab, and some documentation sites do; static PDF exports do not).

flowchart TD
 A[Docs] --> B[API Reference]
 click A "https://example.com/docs" "Open docs"
 click B "https://example.com/api" "Open API"



You can also bind a JavaScript callback or open the link in a new tab by adding _blank as a fourth argument.



What tips help you write cleaner Mermaid diagrams?



After working with Mermaid for a while, these habits make a real difference:



    

  • Use short, unique node IDs. Single letters or short words (A, B, Step1, Step2) keep your source readable. Put the display label inside brackets.
    • 

  • Break large charts into subgraphs. Anything over 15–20 nodes benefits from logical grouping.
    • 

  • Pick a direction and stick with it. Mixing TD and LR in the same top-level chart creates confusing layouts.
    • 

  • Comment your code. Mermaid supports %% this is a comment syntax. Use it to explain non-obvious decisions.
    • 

  • Test incrementally. Add a few nodes at a time in the live editor rather than writing 50 lines and debugging all at once.
    • 

  • Keep labels short. Long labels stretch nodes and distort the layout. Use tooltips or footnotes for extra detail.
    • 




Where does Mermaid fit among other flowchart tools?



Mermaid isn't the only text-to-diagram option. Tools like PlantUML, D2, Graphviz, and Kroki each have their own syntax and strengths. The tradeoff is usually between syntax simplicity, feature depth, and ecosystem support. Mermaid's advantage is broad platform support you'll find it embedded in tools your team already uses. If you want to see how it stacks up feature-by-feature, check out our comparison of interactive flowchart scripting tools.



Quick-reference syntax table



    

  • Start flowchart: flowchart TD or flowchart LR
    • 

  • Rectangle: A[text]
    • 

  • Rounded: A(text)
    • 

  • Diamond: A{text}
    • 

  • Circle: A((text))
    • 

  • Database: A[(text)]
    • 

  • Arrow: A --> B
    • 

  • Labeled arrow: A -->|label| B
    • 

  • Dotted line: A -.-> B
    • 

  • Thick arrow: A ==> B
    • 

  • No arrow: A --- B
    • 

  • Subgraph: subgraph Name ... end
    • 

  • Style: style A fill:#color
    • 

  • Comment: %% comment text
    • 




Before you publish your next diagram, run through this checklist



    

  • Did you declare a flow direction (TD, LR, etc.)?
    • 

  • Are all node IDs unique and all labels wrapped correctly?
    • 

  • Does every subgraph have a matching end?
    • 

  • Have you escaped special characters in labels with quotes?
    • 

  • Is the diagram readable at a glance, or does it need subgraph grouping?
    • 

  • Did you test the syntax in the Mermaid Live Editor before committing?
    • 

  • If you styled nodes, do the colors have enough contrast for accessibility?
    • 




Start with the live editor, build one section at a time, and keep the reference list above handy. You'll find that after a few diagrams, most of the syntax sticks and the parts that don't are worth bookmarking in this guide for quick lookup.