If you've ever needed to explain a process, decision tree, or system workflow to someone, you know how powerful a good flowchart can be. Flowcharts turn abstract steps into something visual that anyone can follow. But drawing them with traditional tools dragging boxes, connecting arrows, adjusting layouts gets tedious fast, especially when your process changes. That's where Mermaid markup comes in. You write simple text, and it generates a flowchart for you. No mouse-dragging. No layout headaches. If you want a faster, code-based way to create flowcharts that live inside your documentation, learning Mermaid is worth your time.

What is Mermaid markup, and how does it make flowcharts?

Mermaid is a lightweight diagram-as-code tool that converts plain text descriptions into visual diagrams. Instead of opening a drawing application and placing shapes manually, you write a few lines of text using a simple syntax. Mermaid's JavaScript library reads that text and renders a flowchart in SVG format.

The syntax is straightforward. You define a flowchart using keywords like graph (or flowchart), node labels, and arrow connectors. For example:

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

This produces a top-down flowchart with a decision diamond, two outcome paths, and a loop. No drawing skills needed just readable text.

You can explore more Mermaid diagram code examples if you want to see what other diagram types look like in this format.

Why would someone use Mermaid instead of a drag-and-drop tool?

Drag-and-drop tools like draw.io or Lucidchart work fine for one-off diagrams. But Mermaid shines in specific situations:

  • Version control. Because flowcharts are plain text, you can track changes in Git just like code. You see exactly what changed and when.
  • Living documentation. When your process changes, you edit a few lines of text instead of redrawing a whole diagram.
  • Platform integration. Mermaid works natively in GitHub, GitLab, Notion, Obsidian, Confluence, and many other tools. You don't need a separate app or export step.
  • Consistency. The rendering engine handles layout, spacing, and arrow routing automatically. No more misaligned boxes.
  • Speed. For anyone comfortable with text, writing a flowchart in Mermaid is faster than clicking through a GUI after a short learning curve.

If you're a developer, technical writer, or project manager who already works in markdown-based tools, Mermaid fits into your workflow without extra steps.

How do you write your first flowchart in Mermaid?

Start with the graph keyword followed by a direction. The direction tells Mermaid which way the chart flows:

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

Next, define your nodes. Each node has an identifier and a label wrapped in a shape. The shape you choose changes the visual meaning:

  • [Text] rectangle (process step)
  • {Text} diamond (decision point)
  • (Text) rounded rectangle (start/end)
  • [[Text]] subroutine shape
  • [(Text)] cylinder (database)
  • /Text/ parallelogram (input/output)

Connect nodes with arrows. Use --> for a standard arrow, and add text to the connection by placing it between pipe characters:

flowchart LR
 A[Place order] --> B{In stock?}
 B -->|Yes| C[Ship item]
 B -->|No| D[Notify customer]
 C --> E[Complete]
 D --> E

This creates a left-to-right flowchart for an order fulfillment process. The decision diamond asks "In stock?" and branches into two outcomes that both reach "Complete."

You can find a broader collection of flowchart syntax patterns in this Mermaid flowchart syntax reference.

What are the basic building blocks of a Mermaid flowchart?

Every Mermaid flowchart uses the same core elements. Understanding these gives you enough to draw most diagrams:

Nodes

A node is any box, shape, or label on your chart. Define one by writing its ID and label on a line:

A[This is a process step]

The letter A is the ID (used for connecting lines). The text inside the brackets is what renders on screen.

Edges (arrows)

Edges connect nodes. The simplest syntax is:

A --> B

This draws an arrow from node A to node B. You can add a label to the arrow:

A -->|Yes| B

Subgraphs

Group related nodes inside a subgraph to organize complex flowcharts:

subgraph Authentication
 A[Login page] --> B[Validate credentials]
 B --> C{Valid?}
end

Subgraphs draw a visible box around grouped nodes and keep your chart readable as it grows.

Styling

Mermaid lets you apply inline styles or class-based styles to change colors, borders, and fonts. A quick inline example:

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

For charts with many nodes, define a class once and apply it to multiple nodes to keep your markup clean.

How do you handle decisions and loops in a flowchart?

Most real-world flowcharts include decision points and loops. Mermaid handles both cleanly.

For a decision, use curly braces for the diamond shape and label each outgoing arrow:

graph TD
 A[Check email] --> B{Spam?}
 B -->|Yes| C[Delete]
 B -->|No| D[Read it]

For a loop, connect a node back to an earlier one:

graph TD
 A[Start review] --> B[Read code]
 B --> C{Issues found?}
 C -->|Yes| D[Fix code]
 D --> B
 C -->|No| E[Approve]

The arrow from D back to B creates a visual loop that's easy to follow. No special syntax needed just point back to an existing node ID.

Where can you actually render Mermaid flowcharts?

Mermaid works in more places than you might expect:

  • GitHub and GitLab wrap your Mermaid code in a fenced code block with the mermaid language tag, and it renders automatically in issues, pull requests, and README files.
  • Notion use the built-in Mermaid code block to embed flowcharts directly in pages.
  • Obsidian supports Mermaid natively in markdown notes.
  • Confluence through the Mermaid plugin.
  • VS Code the Mermaid extension previews diagrams as you type.
  • Online editors the official Mermaid Live Editor lets you write and preview flowcharts in your browser with no installation.

If you also work with UML diagrams, you might find the PlantUML sequence diagram syntax useful as a comparison it follows a similar text-to-diagram approach but with different syntax rules.

What common mistakes break Mermaid flowcharts?

Mermaid's syntax is forgiving compared to many tools, but a few mistakes will stop your diagram from rendering:

  • Missing the direction keyword. Every graph or flowchart line needs a direction like TD or LR. Without it, Mermaid throws an error.
  • Inconsistent indentation in subgraphs. Subgraph content needs consistent spacing. Mixing tabs and spaces can cause parse errors.
  • Special characters in labels. Characters like #, ", or ; inside node labels can break rendering. Wrap complex labels in quotes: A["Label with # special chars"].
  • Reusing node IDs accidentally. If two different nodes share the same ID, Mermaid treats them as the same node and merges them.
  • Forgetting arrow syntax. Using a single dash instead of a double dash (A -> B instead of A --> B) won't work.
  • Overly long labels. Long text inside nodes can make your chart wider than the screen. Keep labels short add detail with tooltips or footnotes instead.

How do you make Mermaid flowcharts easier to read?

A flowchart that's hard to read defeats its own purpose. These practical tips help:

  • Keep labels to 3–5 words. Nodes should be scannable. If you need more explanation, add it elsewhere in your documentation.
  • Use consistent direction. Pick TD or LR for the whole chart. Mixing directions within one chart confuses readers.
  • Limit decision branches. If a decision has more than three outcomes, consider breaking the flowchart into sections using subgraphs.
  • Add meaningful arrow labels. "Yes" and "No" work, but more specific labels like "Approved" or "Needs revision" give better context.
  • Use subgraphs to group phases. Sections like "User Input," "Processing," and "Output" help readers orient themselves.
  • Test in the live editor first. Before committing to your documentation, preview your flowchart at mermaid.live to catch rendering issues early.

What's a realistic example of a Mermaid flowchart for a real process?

Here's a flowchart for a bug triage process that a development team might use:

flowchart TD
 A[Bug reported] --> B[Reproduce the bug]
 B --> C{Reproducible?}
 C -->|No| D[Request more details]
 D --> B
 C -->|Yes| E{Severity?}
 E -->|Critical| F[Hotfix immediately]
 E -->|High| G[Sprint backlog]
 E -->|Low| H[Backlog]
 F --> I[Deploy patch]
 G --> J[Assign developer]
 H --> J
 J --> K[Fix and test]
 K --> L[Code review]
 L --> M{Approved?}
 M -->|Yes| I
 M -->|No| K
 I --> N[Close bug]

This covers the full lifecycle: reporting, reproduction, severity assessment, fixing, review, and closure including loops for incomplete information and failed reviews.

Quick checklist before you publish a Mermaid flowchart

  • ✅ Graph direction keyword is set (TD or LR)
  • ✅ Every node has a unique ID
  • ✅ Arrow labels explain decisions clearly
  • ✅ Special characters in labels are wrapped in quotes
  • ✅ Subgraphs are used to organize sections logically
  • ✅ Chart has been previewed in the Mermaid Live Editor
  • ✅ Labels are short (under 5 words per node)
  • ✅ Direction is consistent throughout
  • ✅ Loops and back-connections are intentional, not accidental

Next step: Pick one real process from your work a deployment pipeline, a support escalation, an onboarding flow and write it as a Mermaid flowchart in under 15 minutes. Start with the happy path, then add decision branches. Once you've done it once, the syntax will stick. For more patterns and reusable snippets, browse the full Mermaid code examples collection.