Mermaid is a JavaScript-based diagramming tool that lets you create flowcharts using plain text instead of dragging boxes in a graphic editor. The syntax feels a lot like writing lightweight markup you type short commands, and Mermaid renders a full diagram. If you've ever needed to sketch a process, decision tree, or system flow without leaving your text editor, understanding the flowchart code syntax in Mermaid language is the skill that makes that possible.

What does flowchart code syntax in Mermaid actually look like?

At its core, a Mermaid flowchart starts with the graph or flowchart keyword followed by a direction: TD (top-down), LR (left-right), BT (bottom-top), or RL (right-left). After that, you define nodes and the connections between them using short characters like arrows (-->), dotted lines (-.->), or thick arrows (==>).

Here is a basic example:

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

This code produces a top-down flowchart with a start box, a decision diamond, and two outcomes that loop back. No special software needed just text.

How do you define different node shapes?

Mermaid uses bracket types to control the shape of each node. This is one of the first things people get wrong, so here's a quick breakdown:

  • Rectangle: A[Text] standard box
  • Rounded rectangle: A(Text) rounded corners
  • Circle: A((Text))
  • Diamond: A{Text} used for decisions
  • Stadium: A([Text]) pill shape
  • Subroutine: A[[Text]] double-bordered rectangle
  • Cylindrical (database): A[(Text)]
  • Hexagon: A{{Text}}

Picking the right shape matters because readers expect diamonds for decisions and rectangles for processes. Using odd shapes for standard steps can confuse the audience.

How do you add labels to connections?

You can attach text to any arrow by placing it between the arrow characters. For example:

A -->|Yes| B
A -->|No| C
A -.->|Optional| D
A ==>|Important| E

Each arrow style carries a visual meaning: solid for normal flow, dotted for optional or conditional paths, and thick for emphasis. Label text sits inside the pipe characters.

Can you use subgraphs to group related steps?

Yes. Subgraphs let you cluster nodes under a labeled section, which is useful for showing phases, modules, or departments within a larger process.

graph TD
subgraph Authentication A[Login] --> B[Verify Token] end subgraph Data B --> C[Fetch Records] C --> D[Display] end

Subgraphs render with a surrounding box and a title, making complex diagrams much easier to follow. If your flowchart has more than ten nodes, grouping them into subgraphs is usually a good idea.

What are common mistakes when writing Mermaid flowchart syntax?

Several errors come up repeatedly:

  • Forgetting the graph direction header. Without graph TD or flowchart LR at the top, nothing renders.
  • Mismatched bracket types. Opening with [ and closing with ) breaks the parser.
  • Special characters in node text. Characters like #, {, or () inside labels need to be wrapped in quotes: A["Value (#1)"].
  • Using spaces in node IDs. Node identifiers must be single words or joined with underscores. The display text inside brackets can have spaces, but the ID before it cannot.
  • Undefined nodes. If you reference a node in a connection but never define it with a shape, Mermaid creates an invisible default which can produce unexpected layouts.

You can catch many of these errors early by running your code through an interactive flowchart syntax validator tool before committing it to your documentation.

When should you use Mermaid flowchart syntax instead of a visual editor?

Mermaid works best when your diagrams live alongside code or documentation. If you write in Markdown, maintain docs in a wiki, or version-control your project files, Mermaid flowcharts are text-native and diff-friendly. You can track changes to a diagram the same way you track changes to code.

Visual editors like Lucidchart or draw.io are better when you need pixel-level layout control, complex styling, or presentations for non-technical audiences. But for technical documentation, README files, wikis, and code comments, Mermaid's text-based approach is faster and more maintainable.

How do you handle complex or large flowcharts?

Large diagrams need structure. A few strategies help:

  1. Use subgraphs to break the flow into logical sections.
  2. Keep node IDs short and meaningful. Use checkAuth instead of node3.
  3. Limit connections per node. If one node has six outgoing arrows, consider whether a subgraph or intermediate step would simplify things.
  4. Use link styles for visual clarity. You can apply CSS-like styling: linkStyle 0 stroke:#ff0000 to highlight critical paths.
  5. Direction changes. You can mix directions inside subgraphs one subgraph can flow left-to-right while the main graph flows top-down.

For advanced layout patterns and reusable templates, take a look at these advanced flowchart syntax patterns that cover multi-layered decision flows and cross-module dependencies.

Can Mermaid flowcharts represent real-time or event-driven systems?

Mermaid isn't designed for executable diagrams, but you can model event-driven flows by using decision nodes to represent triggers and branching paths for different event outcomes. Pairing Mermaid with a documentation system that supports live rendering like GitHub, GitLab, Notion, or Obsidian means your flowchart updates automatically when the code changes.

For teams building reactive or event-driven architectures, there are specific patterns for flowchart syntax in real-time systems that show how to represent async operations, timeouts, and error states clearly.

Do all platforms render Mermaid the same way?

Mostly, but not always. The core syntax works across GitHub, GitLab, Notion, Obsidian, VS Code (with extensions), and the official Mermaid Live Editor. However, some platforms support a subset of features. GitHub, for example, renders basic flowcharts well but may lag behind on newer Mermaid features. Always test your diagram on the target platform before publishing.

Quick-start checklist for writing Mermaid flowcharts

  • Start with the direction keyword: graph TD or flowchart LR
  • Define every node's shape using the correct bracket syntax
  • Keep node IDs short and distinct no spaces or duplicates
  • Quote any label text that contains special characters
  • Use the right arrow type for the relationship (solid, dotted, thick)
  • Group related nodes into subgraphs once you exceed 10 nodes
  • Validate your syntax before publishing using a live editor or validator
  • Test rendering on your target platform GitHub, GitLab, Notion, etc.

Start with a simple five-node flowchart, get it rendering correctly, then expand. Most problems come from trying to build the entire diagram at once instead of testing small sections as you go.