Mermaid Diagram Codes for Flowchart Creation: Syntax and Examples

Diagramming with plain text sounds almost too simple to work but Mermaid has changed how developers, technical writers, and product teams build flowcharts. Instead of dragging and dropping shapes in a GUI tool, you write a few lines of code and get a fully rendered diagram. That matters because version-controlled, text-based diagrams are easier to maintain, share, and collaborate on than image files sitting in someone's desktop application. If you've ever opened an old Visio file and couldn't edit it because the license expired, you already understand the problem Mermaid solves.

What exactly are Mermaid diagram codes for flowchart creation?

Mermaid is a JavaScript-based diagramming library that renders diagrams from text-based markup. For flowcharts specifically, you write structured text that defines nodes (shapes) and edges (connections) using a simple syntax. Mermaid then converts that code into an SVG or image flowchart.

A basic Mermaid flowchart looks like this:

flowchart TD
 A[Start] --> B{Is the user logged in?}
 B -- Yes --> C[Show Dashboard]
 B -- No --> D[Show Login Page]
 D --> E[User enters credentials]
 E --> C

This small block of text produces a top-down flowchart with a decision diamond and labeled arrows. No drawing skills needed. The syntax is readable even if you've never used Mermaid before, which is part of why it's gained traction across other JavaScript diagramming libraries as well.

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

Mermaid flowchart codes make the most sense in a few specific situations:

Documentation that lives alongside code. If your team writes docs in Markdown (on GitHub, GitLab, Notion, or Obsidian), Mermaid diagrams render natively or with minimal setup. The diagram becomes part of the document, not a separate file you have to manage.
Version control. Text-based diagrams work with Git. You can see exactly what changed in a diff. Try doing that with a PNG.
Rapid prototyping. When you need to sketch a process fast like mapping out a user authentication flow or a CI/CD pipeline typing a few lines is faster than opening a design tool.
Consistency across teams. Everyone uses the same syntax. There's no "I used a different shape library" problem.

For teams working on cloud architecture or system design documentation, Mermaid offers a lightweight way to keep diagrams in sync with the systems they describe.

How do you build a flowchart in Mermaid step by step?

1. Define the chart direction

Every Mermaid flowchart starts with a direction keyword:

flowchart TD top-down (most common for flowcharts)
flowchart LR left to right (useful for process workflows)
flowchart BT bottom to top
flowchart RL right to left

2. Create nodes with shapes

Mermaid uses brackets to define different shapes:

A[Text] rectangle (process step)
A(Text) rounded rectangle (start/end)
A{Text} diamond (decision)
A((Text)) circle
A>Text] asymmetric shape (flag-like)
A[[Text]] subroutine shape (double-bordered rectangle)

3. Connect nodes with arrows

Arrows define the flow between nodes:

A --> B arrow from A to B
A -- Text --> B arrow with a label
A -.-> B dotted arrow
A ==> B thick arrow
A --- B line without arrowhead

4. Add subgraphs for grouping

When your flowchart gets complex, you can group related steps:

flowchart TD
 subgraph Authentication
 A[Enter credentials] --> B{Valid?}
 B -- Yes --> C[Grant access]
 B -- No --> D[Show error]
 end

This helps readers understand logical sections of a larger process.

What does a real-world flowchart example look like?

Here's a flowchart for an e-commerce checkout process:

flowchart TD
 A[Customer adds item to cart] --> B[Proceed to checkout]
 B --> C{Has account?}
 C -- Yes --> D[Log in]
 C -- No --> E[Guest checkout or register]
 D --> F[Enter shipping details]
 E --> F
 F --> G[Select payment method]
 G --> H{Payment successful?}
 H -- Yes --> I[Order confirmed]
 H -- No --> J[Show payment error]
 J --> G
 I --> K[Send confirmation email]
 K --> L[Update inventory]

This example shows how a decision-heavy process maps cleanly into Mermaid syntax. Each diamond represents a real branching point in the user experience, and every arrow corresponds to a specific system action.

What are common mistakes when writing Mermaid flowchart codes?

Using special characters in labels without quotes. If your node text contains parentheses, brackets, or other symbols, wrap the text in quotes: A["Process (step 1)"].
Forgetting the direction keyword. Without flowchart TD or flowchart LR at the top, the renderer won't know what kind of diagram to build.
Creating node IDs that start with numbers. Node IDs must start with a letter. Use step1 instead of 1step.
Overloading a single diagram. If your flowchart has 30+ nodes, it becomes hard to read. Split it into subgraphs or multiple linked diagrams.
Inconsistent arrow syntax. Mixing --> and -> or using undefined arrow types will break rendering.
Not testing in a renderer before committing. Always preview your diagram in the Mermaid Live Editor before adding it to documentation.

How do you style Mermaid flowcharts?

Mermaid supports basic styling through classDef and class directives:

flowchart TD
 A[Start] --> B[Process]
 B --> C[End]

 classDef startEnd fill:#d4edda,stroke:#155724,color:#155724
 classDef process fill:#cce5ff,stroke:#004085,color:#004085

 class A,C startEnd
 class B process

You can also use style for one-off formatting:

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

Styling is helpful when you want to distinguish between different types of steps (automated vs. manual, success vs. failure paths) without cluttering the diagram with additional labels.

Where can you render Mermaid flowcharts?

Mermaid diagrams work in a growing number of platforms:

GitHub and GitLab both render Mermaid code blocks in Markdown files and pull request descriptions natively.
Notion supports Mermaid blocks for inline diagrams.
Obsidian renders Mermaid in preview mode with live updates.
VS Code with the Mermaid extension, you can preview diagrams as you type.
Static site generators tools like Docusaurus, MkDocs, and Hugo have Mermaid plugins for documentation sites.
Mermaid Live Editor a browser-based tool for writing and previewing diagrams without any setup.

What's the difference between Mermaid flowcharts and Mermaid sequence diagrams?

Flowcharts show processes and decisions. Sequence diagrams show interactions between actors over time. Mermaid supports both, but the syntax is entirely different. If you're mapping a user journey through an application, use a flowchart. If you're documenting how two services communicate via API calls, a sequence diagram fits better. Choosing the wrong diagram type is a common reason diagrams fail to communicate what they should.

Can Mermaid handle complex flowcharts without becoming unreadable?

Yes, but with limits. Here are practical strategies for managing complexity:

Use subgraphs to break the flowchart into logical sections.
Use link labels sparingly. If every arrow has a label, the diagram becomes noisy. Label only the decision branches.
Keep node text short. A node that says "Check if user has admin permissions in the database" should say "Check admin permissions."
Use comments. Mermaid supports %% this is a comment syntax, which helps when revisiting a diagram later.
Split into multiple diagrams if the process crosses more than one system boundary or involves more than 20 decision points.

How does Mermaid compare to other diagram-as-code tools?

Mermaid isn't the only text-based diagramming option. PlantUML, Graphviz DOT, and D2 are alternatives. The main advantage of Mermaid is its wide platform support it runs in browsers without a server, integrates with most Markdown editors, and has a gentler learning curve than Graphviz. PlantUML supports more diagram types but requires a Java runtime for local rendering. If your primary need is flowcharts embedded in documentation, Mermaid is usually the practical choice.

Practical checklist for creating your first Mermaid flowchart

Start with the Mermaid Live Editor at mermaid.live write your code and see the result instantly.
Define your direction (flowchart TD or flowchart LR) based on how your process naturally reads.
List your main steps as simple nodes before adding decisions and branches.
Add decision diamonds only where the process genuinely splits not every step needs a question.
Label arrows on decision branches (Yes/No, Success/Failure) and leave process arrows unlabeled to reduce clutter.
Use subgraphs to group related steps if your diagram exceeds 15 nodes.
Preview on your target platform (GitHub, Notion, Obsidian) to confirm rendering matches expectations.
Commit the source code to version control so the diagram stays in sync with your project.

Next step: Pick one process from your current project an onboarding flow, a deployment pipeline, a support escalation path and write it as a Mermaid flowchart in under 10 minutes. You'll know right away if text-based diagramming fits your workflow.