Mermaid Flowchart Diagram Syntax Guide with Code Examples

If you've ever needed to explain a process, workflow, or decision tree to someone, you know how hard it can be with words alone. That's where flowcharts come in and Mermaid syntax makes creating them surprisingly fast. Instead of dragging boxes around in a drawing tool, you write a few lines of text and get a clean, professional diagram. This is especially useful for developers, technical writers, and anyone who works with documentation in platforms like GitHub, GitLab, or Notion. Learning how to write a flowchart diagram in Mermaid syntax means you can version-control your diagrams, update them instantly, and keep them right alongside your code or docs.

What is Mermaid syntax and why does it work for flowcharts?

Mermaid is a JavaScript-based diagramming tool that uses a simple text-based syntax to generate charts and diagrams. You write plain text, and a renderer converts it into an SVG flowchart. The flowchart is one of Mermaid's most popular diagram types, along with sequence diagrams, Gantt charts, and class diagrams.

Because the output is generated from text, you can store it in a Markdown file, include it in a pull request, or embed it in any platform that supports Mermaid rendering. No image files needed. No design software. Just text that produces a visual.

How do you start a flowchart in Mermaid?

Every Mermaid flowchart begins with the graph keyword (or flowchart they work the same way). You then choose a direction for the layout:

graph TD top to bottom (most common)
graph LR left to right
graph RL right to left
graph BT bottom to top

Here's the simplest possible Mermaid flowchart:

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

This creates two rectangular nodes connected by an arrow. That's your starting point. From here, you build complexity one piece at a time. If you're looking for copy-paste snippets to get going quickly, our Mermaid flowchart code snippets page has ready-to-use examples for common patterns.

How do you define different node shapes?

Mermaid uses bracket and punctuation characters around node IDs to create different shapes. This is one of the first things that trips people up, so here's a breakdown:

A[Text] rectangle (process step)
A(Text) rounded rectangle (start/end terminal)
A{Text} diamond (decision)
A((Text)) circle
A>Text] asymmetric shape (flag-like)
A[[Text]] subroutine (double-bordered rectangle)
A[(Text)) cylindrical (database)
A{{Text}} hexagon (preparation step)

You combine the node ID with the shape syntax. For example:

graph TD
 A(Round Start) --> B{Is it true?}
 B -->|Yes| C[Do this]
 B -->|No| D[Do that]
 C --> E((End))
 D --> E

This gives you a flowchart with a rounded start, a diamond decision, two process rectangles, and a circular end point. The shape choices communicate meaning diamonds signal decisions, rounded shapes signal start/end points. This matters if you want your diagrams to follow standard flowchart conventions.

How do you add arrows and connections between nodes?

Arrows are the lines connecting your nodes. Mermaid offers several connector styles:

A --> B solid arrow
A --- B solid line, no arrow
A -.-> B dotted arrow
A ==> B thick arrow
A -- text --> B or A -->|text| B arrow with a label
A --> B & C one node connecting to multiple nodes at once

Labeled arrows are especially important for decision flows. The text on an arrow typically reads like an answer to the question in the diamond:

graph TD
 Start --> Check{Is input valid?}
 Check -->|Yes| Process[Process data]
 Check -->|No| Error[Show error message]
 Process --> Done[Save results]
 Error --> Done

You can also chain nodes in sequence on a single line to keep your code compact:

graph TD
 A --> B --> C --> D

How do you organize nodes into subgraphs?

When your flowchart grows, grouping related steps into sections helps readability. Mermaid's subgraph feature does this:

graph TD
 A[Receive request]

 subgraph Validation
 B[Check format]
 C[Check permissions]
 end

 subgraph Processing
 D[Transform data]
 E[Save to database]
 end

 A --> B --> C --> D --> E

Each subgraph appears as a labeled, boxed region in the rendered diagram. You can even use arrows between subgraphs by referencing the subgraph ID instead of individual nodes.

What are the most common mistakes when writing Mermaid flowcharts?

Mermaid syntax is forgiving in some ways and strict in others. Here are mistakes that cause most diagram failures:

Special characters in node text. Characters like #, [, (, { inside a label will break the parser. Wrap text containing special characters in quotes: A["Do this #1"]
Missing the direction keyword. Starting with just graph instead of graph TD will produce an error or unexpected layout.
Indentation issues in subgraphs. The end keyword that closes a subgraph must be on its own line. Don't put it on the same line as another statement.
Using spaces in node IDs. Node IDs (the part before the brackets) must not contain spaces. Use underscores or camelCase: my_step or myStep, not my step.
Confusing the direction keyword with the flowchart keyword. graph TD and flowchart TD both work, but don't mix them in the same diagram.

If you want to compare Mermaid's syntax to other approaches, our flowchart markup language comparison shows how it stacks up against alternatives.

Can you style a Mermaid flowchart with colors and classes?

Yes. Mermaid supports inline styles and CSS-like class definitions to control colors, borders, and fonts:

graph TD
 A[Start] --> B[Process]
 B --> C[End]

 style A fill:#4CAF50,stroke:#333,color:#fff
 style C fill:#f44336,stroke:#333,color:#fff

You can also define reusable classes and apply them to multiple nodes:

graph TD
 A[Start] --> B[Process]
 B --> C[End]

 classDef green fill:#4CAF50,stroke:#333,color:#fff
 classDef red fill:#f44336,stroke:#333,color:#fff

 class A green
 class C red

This keeps your diagram code organized and consistent. It's particularly useful when you want to highlight error states, success paths, or different categories of steps.

Where do Mermaid flowcharts actually render?

Mermaid flowcharts work in many tools and platforms, including:

GitHub and GitLab Markdown files (native support)
Notion, Obsidian, and other note-taking apps
VS Code with the Mermaid extension
Static site generators like Hugo and Jekyll
Confluence with the Mermaid plugin
The Mermaid Live Editor for quick testing

This cross-platform support is a major reason developers prefer text-based diagrams. If you're coming from a Python background and want to explore similar approaches with code, check out our Python flowchart code snippets for beginners.

What does a real-world Mermaid flowchart look like?

Here's a flowchart that models a user login process with validation, error handling, and multiple outcomes:

graph TD
 A(User opens login page) --> B[Enter credentials]
 B --> C{Fields empty?}
 C -->|Yes| D[Show validation error]
 D --> B
 C -->|No| E[Submit to server]
 E --> F{Credentials valid?}
 F -->|Yes| G[Generate session token]
 F -->|No| H[Show login error]
 H --> B
 G --> I{2FA enabled?}
 I -->|Yes| J[Prompt for 2FA code]
 J --> K{Code correct?}
 K -->|Yes| L[Redirect to dashboard]
 K -->|No| M[Show 2FA error]
 M --> J
 I -->|No| L

 style A fill:#2196F3,stroke:#333,color:#fff
 style L fill:#4CAF50,stroke:#333,color:#fff
 style H fill:#f44336,stroke:#333,color:#fff
 style M fill:#f44336,stroke:#333,color:#fff

This shows loops (error states going back to input), branching decisions, and color-coded feedback. It's the kind of diagram that would take 20+ minutes in a drawing tool but takes 2 minutes to write in Mermaid once you're comfortable with the syntax.

What should you do next?

Practice is the fastest way to get comfortable with Mermaid flowchart syntax. Open the Mermaid Live Editor and start with a simple three-node chart. Then add decisions, subgraphs, and styling as you go.

Quick checklist for your next Mermaid flowchart:

Choose your direction (TD or LR) based on how your process naturally flows
Define all nodes first with meaningful IDs and clear labels
Use the right shapes rectangles for processes, diamonds for decisions, rounded for start/end
Add labeled arrows on decision branches so readers know what each path means
Wrap special characters in quotes inside node labels
Use subgraph to group related steps when the chart exceeds 10–15 nodes
Apply color with style or classDef to highlight key paths or states
Test in the live editor before committing to your repo or docs

Start with one real process you understand maybe a deploy pipeline, an onboarding flow, or a support escalation path and diagram it from scratch. You'll internalize the syntax faster than reading another tutorial.