Mermaid Flowchart Syntax Examples for Beginners

If you've ever wanted to create a flowchart without dragging boxes around in a clunky diagram tool, Mermaid might be exactly what you need. Mermaid is a lightweight markup language that turns plain text into diagrams. You write simple syntax, and it renders a flowchart. For beginners, the syntax can look strange at first but once you see a few real examples, it clicks fast. This article walks you through practical Mermaid flowchart examples so you can start writing your own diagrams today.

What Is Mermaid Flowchart Syntax?

Mermaid flowchart syntax is a text-based way to define the shapes, connections, and labels in a flowchart. Instead of using a visual editor, you write short lines of code that describe each node (step) and the arrows between them. Mermaid then renders these into a clean diagram you can embed in documentation, GitHub README files, wikis, or any tool that supports Mermaid rendering.

The basic structure looks like this:

flowchart TD
A[Start] --> B[Do something]
B --> C[End]

TD means "top down." Each line defines a node and an arrow. The letters inside brackets become the visible text. It's that simple at the base level and everything else builds on this pattern.

Why Should Beginners Learn Mermaid Instead of Using a Visual Tool?

Visual diagram tools like Lucidchart or draw.io work well, but they come with friction. You need an account, a browser tab, mouse precision, and time. Mermaid removes most of that. You type the diagram in a text editor, commit it to version control, and it renders anywhere Mermaid is supported.

For developers, technical writers, and product teams, this matters because diagrams live alongside your code and documentation. If a process changes, you edit a few lines of text not redraw 20 boxes. If you're curious how Mermaid compares to other text-based diagram tools, we've written a comparison of Mermaid, Graphviz, and D2 flowchart syntax that breaks down the differences.

How Do You Define Nodes in Mermaid?

Nodes are the boxes, diamonds, and circles in your flowchart. In Mermaid, you define a node by giving it an ID and a label. The ID is what you use to connect nodes with arrows. The label is what viewers see.

Here are the most common node shapes:

Rectangle: A[Text here] the default box shape
Rounded rectangle: A(Text here) often used for start/end
Diamond: A{Text here} used for decisions
Circle: A((Text here)) used for connectors
Stadium/rounded pill: A([Text here])
Parallelogram: A[/Text here/] often used for input/output

You don't need to memorize all of these. Rectangles and diamonds cover most beginner flowcharts. You'll pick up the rest as you go.

How Do You Connect Nodes with Arrows?

Arrows define the flow between steps. The basic arrow syntax is -->. You can also add text to arrows to describe the connection.

Here's a simple decision flowchart:

flowchart TD
  Start(Start) --> Check{Is it working?}
  Check -->|Yes| Done(Great, ship it)
  Check -->|No| Fix(Fix the bug)
  Fix --> Check

The |text| syntax between the arrow markers adds a label to the connection. Notice the last line creates a loop Fix goes back to Check. That's how you show iterative processes in a flowchart.

Arrow types you'll use most:

--> solid arrow (standard flow)
--- solid line with no arrowhead
-.-> dotted arrow
==> thick arrow

What Does a Complete Beginner Flowchart Look Like?

Let's build a real one from scratch. Say you want to document a simple login flow:

flowchart TD
  A([User opens app]) --> B[/Enter credentials/]
  B --> C{Valid credentials?}
  C -->|Yes| D[Load dashboard]
  C -->|No| E[Show error message]
  E --> B
  D --> F([User is logged in])

This uses a rounded start node, a parallelogram for input, a diamond for the decision, rectangles for actions, and a rounded end node. It's clean, readable, and takes under a minute to write.

If you want a broader set of syntax patterns and a quick-reference sheet, our diagram-as-code cheat sheet covers multiple markup languages side by side.

Can You Change the Direction of a Mermaid Flowchart?

Yes. The direction keyword after flowchart controls layout:

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

Use TD for most process flows. Use LR when you want a wider, horizontal layout good for decision trees or pipeline diagrams. The direction you pick depends on how many branches your flowchart has and where it will be displayed.

How Do You Style Nodes and Links in Mermaid?

Mermaid lets you add basic styling with style and classDef. Here's an example:

flowchart TD
  A[Submit form] --> B[Validate data]
  B --> C[Save to database]
  style A fill:#e0f7fa,stroke:#006064
  style C fill:#c8e6c9,stroke:#2e7d32

You can also define reusable classes:

classDef success fill:#c8e6c9,stroke:#2e7d32
classDef error fill:#ffcdd2,stroke:#c62828
class C success
class D error

Styling is optional. For most internal documentation, the default look is fine. Add color when you need to draw attention to specific steps like highlighting error paths or success states.

What Are Common Mistakes Beginners Make with Mermaid Syntax?

Forgetting the direction keyword. Writing flowchart alone without TD or LR can cause layout issues. Always specify direction.
Using special characters in labels without quotes. If your node text contains parentheses or brackets, wrap it in double quotes: A["Label with (parentheses)"].
Mismatched node shapes. If you open a bracket on one side but close with a different type, Mermaid won't render the diagram. Keep your shapes consistent: [], (), {}, etc.
Not testing in a renderer. Write your syntax in the Mermaid Live Editor before pasting it into your docs. It catches errors fast.
Overcomplicating the diagram. If your flowchart has 30+ nodes, break it into smaller sub-flowcharts or link to separate diagrams. Readability matters more than completeness.

How Do You Add Subgraphs to Group Related Steps?

Subgraphs let you visually group related nodes inside a labeled container. This is useful when your flowchart has distinct phases.

flowchart TD
  subgraph Input
    A[Read file] --> B[Parse data]
  end
  subgraph Processing
    C[Transform data] --> D[Validate]
  end
  B --> C
  D --> E[Output result]

Subgraphs render as bordered regions with a title. They help readers understand the structure at a glance without reading every node label.

Where Can You Use Mermaid Flowcharts?

Mermaid is supported in a growing number of tools:

GitHub renders Mermaid blocks in markdown files and issues
GitLab same markdown support in wikis and READMEs
Notion supports Mermaid via code blocks
Obsidian renders Mermaid in notes
VS Code preview with extensions like "Markdown Preview Mermaid Support"
Confluence via plugins
Hugo, Docusaurus, MkDocs static site generators with built-in or plugin-based support

This wide support is part of why Mermaid has become the go-to choice for text-based flowcharts. Your diagrams travel with your content instead of living in a separate file format.

What Should You Try Next After Learning the Basics?

Start small. Pick one real process something you do at work or in a personal project and diagram it in Mermaid. A deployment checklist, a bug triage flow, or a user onboarding sequence all work well.

Once you're comfortable with basic flowcharts, explore Mermaid's other diagram types: sequence diagrams, Gantt charts, class diagrams, and state diagrams all use similar markup principles. The patterns you've learned here transfer directly.

For a broader look at how different diagram-as-code tools compare, check out our syntax comparison of Mermaid, Graphviz, and D2. And if you want a downloadable quick reference, the flowchart markup cheat sheet covers all the syntax patterns in one place.