Mermaid Flowchart Syntax Code Examples for Developers

If you've ever needed to visualize a process, explain a system architecture to a teammate, or document decision logic inside a codebase, you've probably wished for a quick way to draw flowcharts without leaving your editor. That's exactly where Mermaid flowchart syntax code examples come in. Mermaid lets you write diagrams using plain text no drag-and-drop tools, no image files to manage. You write code, and it renders a flowchart. For developers who live in Markdown files, pull requests, and wikis, this is a practical skill worth learning.

What is Mermaid flowchart syntax?

Mermaid is a JavaScript-based diagramming tool that turns text descriptions into visual diagrams. The flowchart (formerly called "graph") syntax is one of its most popular diagram types. You define nodes (shapes) and links (arrows) using a simple, readable syntax that looks a bit like pseudocode.

Here's the most basic example:

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

This creates a top-down flowchart with a start node, a decision diamond, and two outcome paths. graph TD means the flow goes top to bottom. You can also use graph LR for left-to-right layouts. If you're brand new to this, our beginner's reference guide for flowchart syntax codes covers the foundations in more detail.

How do you define different node shapes in Mermaid?

Mermaid uses brackets and parentheses to change node shapes. This matters because standard flowchart conventions use specific shapes for specific meanings rectangles for processes, diamonds for decisions, rounded boxes for start/end points.

A[Text] Rectangle (process step)
A(Text) Rounded rectangle (start/end)
A{Text} Diamond (decision)
A((Text)) Circle
A>Text] Asymmetric/flag shape
A[[Text]] Subroutine (double-bordered rectangle)
A[/Text/] Parallelogram (input/output)
A[\Text\] Parallelogram alt
A{{Text}} Hexagon

If you want to understand when to use each shape and how these compare to formal UML flowchart notation symbols, that's worth reviewing before you build diagrams for technical documentation.

How do you connect nodes with different arrow types?

Links between nodes use different syntax depending on the arrow style you need:

A --> B Arrow with text (open link)
A --- B Line without arrowhead
A -->|label| B Arrow with a label
A -.-> B Dotted arrow
A ==> B Thick arrow
A -.->|label| B Dotted arrow with label
A ==>|label| B Thick arrow with label

Here's a real-world example showing a deployment decision flow:

graph LR A[Push Code] --> B[Run Tests] B --> C{Tests Pass?} C -->|Yes| D[Deploy to Staging] C -->|No| E[Fix Failures] E --> B D --> F[QA Review] F -->|Approved| G[Deploy to Production] F -->|Rejected| E

This kind of diagram works well in README files, technical specs, or embedded directly in documentation sites that support Mermaid rendering.

Can you add subgraphs for grouped logic?

Yes. Subgraphs let you group related nodes under a labeled section. This is useful for showing phases, systems, or swimlane-style groupings within a single flowchart.

graph TD subgraph Frontend A[User Clicks Button] --> B[Send API Request] end subgraph Backend C[Receive Request] --> D[Query Database] D --> E[Return Response] end B --> C E --> F[Render Data]

Subgraphs render as bordered boxes around the grouped nodes, giving readers a clear visual separation between logical sections of your system.

How do you write Mermaid flowcharts inside Markdown files?

If you're writing documentation in Markdown, you can embed Mermaid code using a fenced code block with the mermaid language identifier:

```mermaid graph TD A[Write Code] --> B[Review PR] B --> C[Merge] ```

This works on GitHub, GitLab, Notion, Obsidian, and many documentation platforms. We cover the full setup process in our guide on how to write flowchart syntax code in Markdown.

What are common mistakes when writing Mermaid flowcharts?

Developers run into a few recurring issues:

Missing quotes around labels with special characters. If your node text contains parentheses, brackets, or other symbols, wrap the label in quotes: A["Function (async)"].
Using the wrong direction keyword. Older tutorials reference graph vs flowchart. Both work, but flowchart is the newer keyword and supports some extra features.
Forgetting that node IDs and labels are separate. A[Start] means the node ID is A and the visible label is Start. If you later reference A as Start, Mermaid won't recognize it.
Indentation problems. Mermaid is sensitive to whitespace inside subgraphs. Stick to consistent indentation (two spaces) to avoid parsing errors.
Overcrowded diagrams. A flowchart with 30+ nodes becomes unreadable. Split complex flows into multiple diagrams or use subgraphs to improve clarity.

What are some useful but lesser-known Mermaid features?

Styling nodes with classes

You can apply CSS-like styles to individual nodes or groups:

graph TD A[Normal Step] --> B[Error Step] classDef error fill:#f96,stroke:#333,color:#fff class B error

This is helpful when you want to visually highlight error states, warnings, or success paths in a diagram.

Clickable nodes

Mermaid supports interactive nodes that link to URLs:

graph TD A[Docs] --> B[API Reference] click A "https://example.com" "Visit docs"

This works in environments that render Mermaid with interactivity enabled, like documentation sites built with tools such as MkDocs or Docusaurus.

Comments

You can add comments using %% at the start of a line. This is useful for annotating complex diagrams during development:

graph TD %% This section handles login flow A[Enter Credentials] --> B{Valid?} B -->|Yes| C[Dashboard] B -->|No| D[Show Error]

When should you use Mermaid instead of a drawing tool?

Mermaid works best when:

Your diagram lives alongside code (in a repo, wiki, or doc site).
You want version-controlled diagrams that update with pull requests.
You need to create diagrams quickly without switching tools.
Your team uses platforms that natively render Mermaid (GitHub, GitLab, Notion, Obsidian).

Traditional drawing tools (like Lucidchart, draw.io, or Miro) are still better for polished presentations, complex layouts with precise positioning, or diagrams that need custom branding. Mermaid trades pixel-perfect control for speed and code-native convenience.

How do you preview Mermaid diagrams while editing?

You have several options:

Mermaid Live Editor A browser-based tool where you type Mermaid code on the left and see the rendered diagram on the right in real time.
VS Code extensions The "Mermaid Chart" or "Markdown Preview Mermaid Support" extensions render diagrams inside your editor's preview pane.
GitHub/GitLab rendering Push a Markdown file with a Mermaid code block and it renders automatically in the file view.
Browser-based renderers Tools like Mermaid.js can render diagrams client-side on any web page.

For most developers, the live editor is the fastest way to prototype, and the VS Code extension is the most convenient for daily workflow.

Practical checklist for writing your first Mermaid flowchart

Start with graph TD (top-down) or graph LR (left-right) depending on your flow's natural reading direction.
Define all nodes first with meaningful IDs and clear labels.
Use the correct bracket syntax for each shape type (rectangles, diamonds, circles).
Add labeled arrows for decision branches so readers understand the logic.
Use subgraphs if your diagram has more than 10 nodes to keep it organized.
Wrap special characters in quotes to avoid parsing errors.
Preview your diagram in the Mermaid Live Editor before committing.
Keep diagrams focused one flowchart per process, not one diagram for an entire system.
Test rendering on your target platform (GitHub, docs site, wiki) to confirm it displays correctly.
Version control your diagrams alongside the code they document.