How to Write Flowchart Syntax in Mermaid Language

If you've ever needed to map out a process, explain a decision tree, or document a system workflow inside a document or README file, learning how to write flowchart syntax in Mermaid language is one of the fastest ways to do it. Mermaid lets you create flowcharts using plain text instead of dragging boxes around in a drawing tool. That means your diagrams live right alongside your code, they're version-controlled, and anyone on your team can edit them without special software. Understanding the syntax removes the guesswork and lets you build clear diagrams on the first try.

What exactly is Mermaid flowchart syntax?

Mermaid is a JavaScript-based diagramming tool that renders diagrams from text-based definitions. The flowchart syntax is a specific set of rules you follow to tell Mermaid what shapes to draw, how to connect them, and what labels to display. Think of it as a shorthand language: you write a few lines of text, and Mermaid turns them into a visual flowchart.

The syntax starts with a declaration like flowchart TD (top-down) or flowchart LR (left-right), followed by node definitions and link descriptions. Each node gets an ID and a label, and each arrow connects two nodes together. If you've ever written pseudocode, the learning curve here is short.

How do you define nodes and shapes in Mermaid?

Nodes are the building blocks of any Mermaid flowchart. You define them by pairing an ID with a label. The shape of the node depends on the brackets you wrap around the label text:

Rectangle: A[Step one] uses square brackets
Rounded rectangle: A(Step one) uses parentheses
Circle: A((Step one)) uses double parentheses
Rhombus (diamond): A{Is this valid?} uses curly braces
Parallelogram: A[/Input data/] uses forward slashes inside brackets
Hexagon: A{{Prepare data}} uses double curly braces

Each node ID must be unique. The label inside the brackets is what users see in the rendered diagram. Here's a quick example:

flowchart TD
  A[Start] --> B{Is input valid?}
  B -->|Yes| C[Process data]
  B -->|No| D[Show error]

This creates a simple top-down flowchart with a decision diamond. If you want a refresher on all the available node shapes, our flowchart markup syntax cheat sheet covers every option in one place.

How do you connect nodes with arrows?

Links between nodes use arrow notation. Here are the most common patterns:

Solid arrow: A --> B
Dotted arrow: A -.-> B
Thick arrow: A ==> B
Arrow with label: A -->|Label text| B
Line without arrow (no direction): A --- B

Labels on links are helpful when you have decision branches. They let you describe why the flow goes one way versus another, like "Yes" or "Approved" on each path leaving a diamond node.

Can you group nodes or create subgraphs?

Yes. Mermaid supports subgraphs, which let you group related nodes under a labeled section. This is useful for showing phases of a process or separating concerns in a complex diagram.

Here's the syntax:

subgraph Authentication
A[Enter credentials] --> B[Validate]
end

Subgraphs render as a visible container around the grouped nodes, making your diagram easier to read when it has many steps.

What does a complete flowchart example look like?

Let's put it all together. Say you want to document a simple user signup flow:

flowchart TD
  Start([User visits signup page]) --> A[Enter email and password]
  A --> B{Email already registered?}
  B -->|Yes| C[Show "account exists" message]
  C --> A
  B -->|No| D[Create account]
  D --> E[Send confirmation email]
  E --> F([Done])

This uses a rounded start/end node (stadium shape with parentheses), rectangular process steps, a diamond for the decision, and a link that loops back when the email is already taken. Developers often use this kind of diagram in documentation, onboarding guides, or pull request descriptions. For more reference material aimed at engineers, see our flowchart code syntax reference for software developers.

What are the most common mistakes when writing Mermaid flowchart syntax?

Missing or mismatched brackets. If you open a node with [ but close with ), Mermaid won't render it. Double-check that every bracket pair matches.
Duplicate node IDs. Using the same ID twice causes unexpected behavior. Each ID like A, B, C should appear only once as a definition.
Special characters in labels. Characters like [, }, or " inside labels can break the parser. Wrap problematic text in quotes: A["Use [brackets] here"].
Forgetting the flowchart direction. The first line must declare a direction like flowchart TD or flowchart LR. Without it, the diagram won't render.
Overcrowding a single diagram. Huge flowcharts with 40+ nodes become unreadable. Break them into smaller subgraphs or separate diagrams.

Tips to write cleaner Mermaid flowcharts

Use meaningful IDs. Instead of A, B, C, try validate_input, save_record. It won't show in the diagram, but it makes the source text readable for anyone editing it later.
Keep labels short. Long labels make diagrams wide and hard to follow. Aim for five words or fewer per node.
Pick the right direction. Use TD (top-down) for decision trees and LR (left-right) for process flows with many sequential steps.
Use link labels on every decision branch. Unlabeled arrows leaving a diamond node confuse readers fast.
Test in a live editor. The Mermaid Live Editor renders your code in real time so you can spot mistakes before committing.

Where does Mermaid flowchart syntax actually work?

Mermaid diagrams render natively in many tools you might already use:

GitHub Markdown files with mermaid code blocks render automatically in pull requests and READMEs.
GitLab Same native support in Markdown.
Notion Embed Mermaid blocks directly in pages.
VS Code Extensions like "Markdown Preview Mermaid Support" let you preview diagrams while writing.
Confluence, Obsidian, Typora All support Mermaid rendering out of the box or with plugins.

This broad support is one reason the syntax is worth learning. You write it once and it works across tools without exporting images.

Next steps to put this into practice

Start by picking one workflow you've been explaining with words alone maybe a deployment process, a bug triage flow, or an onboarding checklist. Open the Mermaid flowchart syntax walkthrough alongside the syntax cheat sheet, and start writing node by node. Test each line in the live editor as you go. Within 10 minutes, you'll have a diagram you can paste into your docs, your repo, or your team wiki. The more you write, the faster it gets and you'll wonder why you ever used a drag-and-drop tool for simple flowcharts.