How to Create Flowcharts Using Mermaid Code

Flowcharts are one of the simplest ways to explain a process. Whether you're mapping out a login system, a customer support workflow, or a deployment pipeline, a flowchart turns complexity into something visual and understandable. The problem? Most diagramming tools require you to click, drag, and manually position every box and arrow. That takes time, and every small change means reworking the layout.

Mermaid code solves this. It lets you write flowcharts using plain text, and a renderer turns that text into a diagram automatically. You define the structure, and Mermaid handles the positioning, arrows, and styling. If you've ever wished you could describe a flowchart the same way you'd describe it to a colleague in simple steps Mermaid gets you close to that.

This guide walks you through exactly how to create flowcharts using Mermaid code, from the basic syntax to practical examples you can use right away.

What Is Mermaid Code and How Does It Work for Flowcharts?

Mermaid is a JavaScript-based diagramming tool that uses a markdown-inspired text syntax. You write short, readable code, and Mermaid renders it as a visual diagram. It was created by Knut Sveidqvist and is now widely used in documentation platforms, wikis, and developer tools.

For flowcharts specifically, Mermaid uses a graph declaration at the top to define the diagram direction, followed by a series of nodes and connections. Here's the basic structure:

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

In this example, graph TD means the flowchart goes top-down. Each letter represents a node, and the arrows between them define the flow. The shapes rectangles, diamonds, rounded boxes are controlled by the bracket style you use around each node ID.

Why Would You Use Mermaid Instead of a Regular Diagram Tool?

You might wonder why you'd write code instead of using a drag-and-drop tool. There are a few practical reasons developers and technical writers prefer Mermaid:

Version control friendly. Since flowcharts are plain text, you can store them in Git and track changes over time, just like source code.
Fast to edit. Changing a connection or adding a step means editing a line of text, not repositioning boxes manually.
Works in documentation. Mermaid renders natively in GitHub, GitLab, Notion, Obsidian, and many wiki platforms. You don't need a separate image file.
Consistent output. The layout engine handles positioning, so your diagrams always look clean without manual tweaking.

If you're already documenting software or writing technical specs, Mermaid fits naturally into your workflow. It pairs well with other diagram types too for example, you can use similar syntax to build sequence diagrams for showing interactions between systems.

How Do You Write Your First Flowchart in Mermaid?

Let's build a simple flowchart step by step. Say you want to map out a basic decision process: a user tries to log in, and the system checks their credentials.

graph TD
 A[User visits login page] --> B[Enter credentials]
 B --> C{Valid credentials?}
 C -->|Yes| D[Redirect to dashboard]
 C -->|No| E[Show error message]
 E --> B

Here's what each part does:

graph TD sets the direction to top-down. You can also use graph LR for left-to-right layouts.
A[User visits login page] creates a rectangular node with that label.
C{Valid credentials?} creates a diamond shape, which signals a decision point.
C -->|Yes| D adds an arrow with the label "Yes" leading to the next node.
E --> B loops the flow back to the credential entry step.

That's it. With six lines of code, you have a complete login flow diagram.

What Node Shapes Can You Use in Mermaid Flowcharts?

The shape of each node depends on the bracket type you use in the syntax. This is one of the first things to learn because it directly affects how readable your diagram is. Here are the most common shapes:

Rectangle: A[Text] standard process step
Rounded rectangle: A(Text) often used for start/end points
Diamond: A{Text} decision points with yes/no branches
Circle: A((Text)) used for connectors or reference points
Asymmetric (flag): A>Text] occasionally used for special annotations
Hexagon: A{{Text}} preparation or manual operations
Parallelogram: A[/Text/] input/output operations

Using the right shape for the right purpose makes your flowchart easier to read without needing a legend. Diamonds for decisions, rectangles for actions, and rounded boxes for start/end states is a common convention.

How Do You Add Directions and Subgraphs?

Mermaid supports four flow directions: TD (top-down), LR (left-right), BT (bottom-top), and RL (right-left). For most flowcharts, TD or LR work best depending on the complexity and width of your diagram.

When a flowchart gets large, you can group related nodes into subgraphs to keep things organized:

graph TD
 A[Start] --> B[Load config]
 
 subgraph Authentication
 C[Check token] --> D{Token valid?}
 D -->|Yes| E[Allow access]
 D -->|No| F[Redirect to login]
 end
 
 B --> C
 E --> G[Show dashboard]

Subgraphs create visual boundaries around grouped nodes, making complex diagrams easier to scan. This is especially useful when you're documenting a system with multiple modules or phases.

What Are Common Mistakes When Writing Mermaid Flowcharts?

Mermaid's syntax is forgiving in some ways, but a few mistakes trip people up regularly:

Special characters in labels. If your node text includes characters like parentheses, quotes, or curly braces, you need to wrap the label in quotes: A["User enters (email)"]. Forgetting this causes rendering errors.
Missing semicolons or line breaks. Mermaid needs each connection on its own line. Cramming multiple connections onto one line without semicolons breaks the parser.
Inconsistent node IDs. If you define a node as Login[Login Page] in one place and reference it as login[Login Page] somewhere else, Mermaid treats them as two different nodes. IDs are case-sensitive.
Overly long labels. Long text in nodes can stretch the diagram awkwardly. Keep labels short four to six words and add detail through tooltips or footnotes if needed.
Forgetting direction. If you omit graph TD or graph LR, Mermaid defaults to top-down, which may not be what you want. Always declare the direction explicitly.

How Do You Style a Mermaid Flowchart?

You can customize colors, borders, and fonts using Mermaid's style and classDef directives. This helps when you want to highlight specific parts of a flow, like error states or success paths.

graph TD
 A[Submit form] --> B{Valid?}
 B -->|Yes| C[Save data]
 B -->|No| D[Show error]
 
 style C fill:#d4edda,stroke:#28a745
 style D fill:#f8d7da,stroke:#dc3545

You can also define reusable classes with classDef and apply them across multiple nodes:

classDef success fill:#d4edda,stroke:#28a745
classDef error fill:#f8d7da,stroke:#dc3545

class C success
class D error

This keeps your styling consistent and makes the code easier to maintain as the diagram grows.

Where Can You Render Mermaid Flowcharts?

One of Mermaid's strengths is how widely it's supported. You have several options for rendering your code into a visual diagram:

GitHub. GitHub renders Mermaid code blocks natively in markdown files, pull requests, and issues. Just wrap your code in a mermaid fenced code block.
GitLab. Similar to GitHub, GitLab supports Mermaid rendering in markdown.
The Mermaid Live Editor. mermaid.live is the official browser-based editor where you can write code and see the output instantly. It also lets you export diagrams as SVG or PNG.
Notion, Obsidian, and Confluence. These tools support Mermaid through built-in blocks or plugins.
VS Code. The Markdown Preview Mermaid Support extension lets you preview Mermaid diagrams directly in your editor.

If you're building documentation alongside your codebase, the ability to keep flowcharts as text files rendered automatically on your platform saves significant time compared to exporting and uploading images.

What Are Some Real-World Examples of Mermaid Flowcharts?

Here are a few practical scenarios where Mermaid flowcharts work well:

Documenting a deployment process:

graph TD
 A[Push to main] --> B[Run CI tests]
 B --> C{Tests pass?}
 C -->|Yes| D[Build Docker image]
 D --> E[Push to registry]
 E --> F[Deploy to staging]
 F --> G{QA approved?}
 G -->|Yes| H[Deploy to production]
 G -->|No| I[Create bug ticket]
 I --> A

Mapping a user onboarding flow:

graph TD
 A[New user signs up] --> B[Send verification email]
 B --> C{Email verified?}
 C -->|Yes| D[Complete profile]
 C -->|No| E[Resend email]
 E --> C
 D --> F[Select plan]
 F --> G[Enter payment info]
 G --> H[Account activated]

These examples show how even moderately complex processes become easy to follow in diagram form. You can find more diagram code patterns in this collection of Mermaid examples for software documentation.

How Do You Keep Complex Flowcharts Readable?

As flowcharts grow beyond 15 or 20 nodes, readability drops quickly. Here are practical ways to manage complexity:

Use subgraphs to group related steps. Label each subgraph so readers understand the section at a glance.
Limit decision branches. If a single decision has more than three outcomes, consider splitting it into multiple steps.
Break into multiple diagrams. A high-level overview flowchart that links to detailed sub-processes is easier to digest than one giant chart.
Keep labels short. Four to six words per node. If you need more detail, use a numbered reference system that maps to a legend below the diagram.
Use consistent styling. Apply colors to distinguish action steps from decision points or error states. This lets readers scan the diagram without reading every label.

Quick Checklist Before You Publish a Mermaid Flowchart

Does the diagram render correctly in your target platform? Always preview before committing.
Are all special characters in node labels properly escaped with quotes?
Is the flow direction (TD vs LR) the best choice for this particular diagram?
Have you used meaningful node IDs that make the code readable for other contributors?
Are decision diamonds labeled with clear yes/no or specific outcome labels?
Does the diagram tell a complete story from start to end, with no dead-end branches?
Have you tested the rendering at different screen widths to make sure it stays legible?

Start small. Write a three-step flowchart for a process you know well, render it in the Mermaid Live Editor, and iterate from there. Once you're comfortable with the basic node types and connections, you'll find that building flowcharts in code is faster than any drag-and-drop tool especially when the diagram needs to change over time.