Mermaid Flowchart Tutorial - Syntax, Examples, and Best Practices

What You Will Learn

How to recognize when Flowchart is the right Mermaid diagram, write the opening declaration, and shape a readable first version.

Best Fit

Product onboarding flows, Backend job pipelines, Support decision trees.

Start Here

Copy the starter example, replace labels with your domain language, then simplify anything that does not help the reader.

Syntax Basics

Start with the diagram declaration, then add the smallest set of labels, relationships, and annotations needed to communicate the idea.

Use flowchart TD, LR, BT, or RL to control direction.
Choose node shapes such as rectangles, diamonds, circles, and rounded boxes.
Label edges with pipes, for example A -->|Yes| B.
Group related steps with subgraphs.

Official Documentation Coverage

The Mermaid documentation for Flowchart covers the following syntax areas. This tutorial condenses those topics into practical guidance for day-to-day documentation.

Basic flowchart syntax

Basic flowchart syntax is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Default nodes and custom node text

Default nodes and custom node text defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Diagram direction

Diagram direction is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Node shapes

Node shapes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Rounded, stadium, subroutine, database, and circle nodes

Rounded, stadium, subroutine, database, and circle nodes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Links, labels, and branches

Links, labels, and branches controls how elements connect. Treat these connections as the main information layer, and label them when direction, ownership, or meaning is not obvious.

Subgraphs

Subgraphs is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Styling and classes

Styling and classes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

How This Tutorial Uses The Official Docs

Mermaid syntax evolves, so the official page remains the primary reference. This tutorial turns that reference material into an authoring workflow, review checklist, and production guidance.

Start with the official grammar

The official Mermaid Flowchart page is the source of truth for syntax changes. Use this tutorial to choose the right authoring pattern, then confirm exact keywords and edge cases in the official reference.

Prioritize the core sections

For the first pass, focus on Basic flowchart syntax, Default nodes and custom node text, Diagram direction, Node shapes. These sections usually explain the minimum structure required for a valid Flowchart.

Add advanced syntax only when it earns its space

Treat Rounded, stadium, subroutine, database, and circle nodes, Links, labels, and branches, Subgraphs, Styling and classes as optional layers. They are valuable when the diagram needs precision, but they should not make the first version harder to read.

Syntax Reference Map

Use this map as a practical reading order for the official syntax page. It separates the first concepts to learn from the advanced details that are better added after the diagram already communicates the right idea.

Phase

Topic

How to use it

Start

Basic flowchart syntax

Basic flowchart syntax is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Does this basic flowchart syntax detail make the flowchart easier to understand or maintain?

Start

Default nodes and custom node text

Default nodes and custom node text defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Does this default nodes and custom node text detail make the flowchart easier to understand or maintain?

Refine

Diagram direction

Diagram direction is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Does this diagram direction detail make the flowchart easier to understand or maintain?

Refine

Node shapes

Node shapes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Does this node shapes detail make the flowchart easier to understand or maintain?

Refine

Rounded, stadium, subroutine, database, and circle nodes

Rounded, stadium, subroutine, database, and circle nodes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Does this rounded, stadium, subroutine, database, and circle nodes detail make the flowchart easier to understand or maintain?

Polish

Links, labels, and branches

Links, labels, and branches controls how elements connect. Treat these connections as the main information layer, and label them when direction, ownership, or meaning is not obvious.

Does this links, labels, and branches detail make the flowchart easier to understand or maintain?

Polish

Subgraphs

Subgraphs is part of the official Mermaid Flowchart syntax surface. Add it when the starter example needs more precision for production documentation.

Does this subgraphs detail make the flowchart easier to understand or maintain?

Polish

Styling and classes

Styling and classes defines the named objects in the diagram. Keep names stable, domain-specific, and short enough to remain readable in exported images.

Does this styling and classes detail make the flowchart easier to understand or maintain?

How To Study The Official Syntax

The official Mermaid page is broad because it documents the full parser surface. For a working tutorial, read it in passes instead of trying to memorize every option at once.

Step 1

Skim the official Flowchart documentation once to understand the full syntax surface before copying examples into production docs.

Step 2

Focus first on Basic flowchart syntax, Default nodes and custom node text, Diagram direction, Node shapes, Rounded, stadium, subroutine, database, and circle nodes because these topics usually explain the core authoring model.

Step 3

After the first diagram renders, revisit the official styling, configuration, and advanced sections only when the diagram needs that extra precision.

Authoring Workflow

This workflow turns the official syntax reference into a repeatable writing process for docs, specs, and product pages.

Step 1

Frame the reader question

Before writing syntax, decide what question the Flowchart should answer. Good diagrams usually answer one question clearly instead of answering several partially.

Step 2

Draft the smallest valid diagram

Start with the declaration for flowchart, add only the required elements, and render it before introducing advanced styling or configuration.

Step 3

Add semantic labels

Replace placeholder names with business or system language that readers already know. Labels should reduce explanation work.

Step 4

Review for maintenance

Remove details that are likely to drift quickly. If a value, date, or dependency changes often, explain who owns the update.

Quick Syntax Cheat Sheet

Use this compact reference when you already know the goal and need to write a valid Mermaid Flowchart quickly.

Declaration

flowchart

Start the code block with flowchart so Mermaid selects the Flowchart renderer.

Core content

Use flowchart TD, LR, BT, or RL to control direction.

Add the smallest number of statements that express the main idea before adding visual polish.

Connections

Label edges with pipes, for example A -->|Yes| B.

Use connections only where they explain ownership, sequence, flow, dependency, or hierarchy.

Advanced topic

Basic flowchart syntax

Use official syntax topics as optional layers, not as requirements for every diagram.

Practice Prompts

Use these prompts after reading the official syntax sections. They force the diagram to stay practical instead of becoming a syntax inventory.

Exercise 1

Create a Flowchart for product onboarding flows using no more than eight visible elements.

Exercise 2

Rewrite the starter example with labels from your own product or engineering domain, then remove any line that does not change the reader's understanding.

Exercise 3

Add one official syntax feature from Basic flowchart syntax, Default nodes and custom node text, Diagram direction and explain why that feature makes the diagram clearer.

Exercise 4

Compare the result with sequence-diagram and state-diagram and write one sentence explaining why Flowchart is still the better fit.

Examples

Copy the example into the Mermaid editor, then adjust labels and relationships for your own documentation.

Basic Decision Flow

A small process with one decision and two outcomes.

flowchart TD
  A([Start]) --> B{Is the user signed in?}
  B -->|Yes| C[Open dashboard]
  B -->|No| D[Show sign in form]
  C --> E([Done])
  D --> E

Example Walkthrough

Read Mermaid examples from top to bottom. The first meaningful line usually selects the diagram parser; the following lines add labels, relationships, values, states, or layout hints.

flowchart TD

This line declares the Mermaid diagram type, which tells Mermaid which parser and renderer to use.

A([Start]) --> B{Is the user signed in?}