Flowcharts are the easiest way to start with Mermaid. In this tutorial you'll build a complete flowchart for a password reset process, one concept at a time. Open the online editor in another tab and follow along.
Step 1: Choose a direction
Every flowchart begins with the flowchart keyword and a direction: TD (top-down), LR (left-right), BT or RL. Top-down suits decision trees; left-right suits pipelines.
flowchart TDStep 2: Add nodes and shapes
A node is an id followed by a label in brackets. The bracket style sets the shape:
| Syntax | Shape | Typical use |
|---|---|---|
| A[Text] | Rectangle | Process step |
| A(Text) | Rounded | Soft step |
| A([Text]) | Stadium | Start / end |
| A{Text} | Diamond | Decision |
| A[(Text)] | Cylinder | Database |
| A[/Text/] | Parallelogram | Input / output |
| A((Text)) | Circle | Connector |
Step 3: Connect nodes with arrows
Use --> for an arrow, --- for a plain line, -.-> for dotted and ==> for thick. Add a label in the middle with -- text --> or -->|text|.
flowchart TD
A([Forgot password]) --> B[/Enter email/]
B --> C{Account exists?}
C -- Yes --> D[Send reset link]
C -- No --> E[Show generic message]
D --> F[User sets new password]
F --> G([Done])Show the same generic message whether or not the account exists — it prevents attackers from discovering registered emails. Diagrams are a great place to document decisions like this.
Step 4: Group steps with subgraphs
Subgraphs draw a box around related nodes. They're ideal for showing which system or team owns which steps.
flowchart LR
subgraph Browser
A[Reset form] --> B[Submit]
end
subgraph Server
C[Validate token] --> D[Hash password] --> E[(Save)]
end
B --> CStep 5: Style your flowchart
Define reusable styles with classDef and attach them with :::. You can also change the whole look with a Mermaid theme.
flowchart TD
A[Request] --> B{Valid?}
B -->|Yes| C[Success]:::ok
B -->|No| D[Error]:::bad
classDef ok fill:#dcfce7,stroke:#16a34a
classDef bad fill:#fee2e2,stroke:#dc2626Step 6: Export and share
In the editor, use Export to download a PNG. Free is 1× with a small watermark, Starter goes to 4× with no watermark, and Pro goes to 8×. JPG, SVG and PDF are on Pro. Share creates a link that opens the diagram in the editor, and signed-in users can publish an embeddable version.
Common flowchart mistakes
- Using
endin lowercase as a label — it closes subgraphs. WriteEndinstead. - Special characters in labels — wrap them in quotes:
A["Price (USD)"]. - Duplicate ids with different labels — the last label wins and arrows connect to the same node.
More fixes are in our guide to Mermaid syntax errors, and the full syntax is on the flowchart reference page.
Subgraphs with their own direction
The six steps above get a chart on the page. The rest of how to create a mermaid flowchart shows up when the picture has to match a real system: groups with their own direction, several arrows declared on one line, edges you can tell apart, comments, quoted labels, and a second complete example.
A subgraph is a labeled box around nodes. Give it an id and a title so you can point at the box later without guessing how Mermaid sanitized the words:
flowchart LR
subgraph edge ["Edge (public)"]
direction TB
Web[Web] --> API[API]
end
subgraph data [Data]
direction TB
Worker[Worker] --> DB[(Primary)]
end
API --> WorkerThe id is edge. The title is Edge (public), quotes included because of the parentheses. Inside the box, direction TB asks for a top-down stack even though the parent chart is LR. The arrow from API to Worker still belongs to the parent, so it runs left to right between the groups. Use the inner direction for the steps a team owns. Use the outer direction for the handoff between teams.
Nest a subgraph when a group contains a group. Close each one with end, and indent so the closers line up with the openers. The word end on its own line always closes the nearest subgraph. It is not a node. If the last step is called end, write Finish["End"] or the closer will swallow the rest of the file. The syntax guide shows that failure next to a fixed file.
You can put a subgraph inside another:
flowchart TB
subgraph region [Region]
direction LR
subgraph pub [Public]
CDN[CDN] --> App[App]
end
subgraph priv [Private]
Svc[Service] --> DB[(DB)]
end
App --> Svc
endLink nodes to nodes, not titles to titles. App --> Svc works because both ids exist. Public --> Private does not, unless you also declared node ids with those names. The title is a caption. The id is the handle. Style the box with the id when you need a fill: style region fill:#f8fafc,stroke:#94a3b8. Keep that fill light and set nothing else until you have read the themes guide, because a hard-coded fill is what breaks dark mode.
A subgraph with one node is usually noise. Group steps that share an owner, a network boundary, or a failure domain. If you can't say why the box exists, delete it and let the arrows speak.
Chaining arrows
A link is one statement. You can still write several on one line, and you should know what that line expands to, because linkStyle counts the expanded links.
Commit --> Test --> Image --> Scan is three links: Commit to Test, Test to Image, Image to Scan. The layout is the same as three separate lines. The difference is that the indexes are fixed by reading left to right.
& fans a link out or in. Commit --> Lint & Test draws Commit to Lint and Commit to Test. Lint & Test --> Image draws Lint to Image and Test to Image. Mix them when a pipeline splits and joins:
flowchart LR
Commit --> Lint & Test
Lint --> Image
Test --> Image
Image --> ScanThat is five links. The first line expands to Commit to Lint and Commit to Test, then Lint to Image, Test to Image, and Image to Scan. If you later insert Commit --> Docs above Lint --> Image, every index from that point moves. Chains are fine. Numbered styles on top of a chain are fragile, which is the next section.
Dotted and thick arrows still work inside a chain: Scan -.-> Report and Image ==> Canary. A label sits in the middle with -->|yes| or -- yes -->. Don't chain so hard that a label has nowhere to live. When an edge needs a sentence, give it its own line.
An invisible link, A ~~~ B, reserves a relationship for layout without drawing a line. Use it when two nodes should stay on the same rank and a visible arrow would lie about a call. Use it rarely. A diagram full of invisible links is a sign the direction or the subgraphs are wrong.
Link styles
linkStyle paints an edge by index, starting at 0, in the order the edges appear in the file. It does not look at labels or ids. This deploy snippet numbers them on purpose:
flowchart LR
Build[Build image] --> Scan[Scan]
Scan --> Canary[Canary]
Canary --> Check{Healthy?}
Check -->|Yes| Prod[Production]
Check -->|No| Rollback[Roll back]
linkStyle 0 stroke:#64748b
linkStyle 3 stroke:#0f766e,stroke-width:2px
linkStyle 4 stroke:#b45309,stroke-dasharray:5 5Index 0 is Build to Scan, the first arrow in the file. Index 3 is the Yes branch. Index 4 is the No branch, drawn dashed so a rollback doesn't look like the happy path. The properties are CSS-ish and comma-separated: stroke, stroke-width, stroke-dasharray. A semicolon where the comma should be is enough to make the line fail.
Because the index is positional, write linkStyle after the links it refers to, and treat it as a last step. If you add a node in the middle of the story, re-count. For a meaning that should survive edits, prefer a dotted or thick arrow, or a label, over a color that depends on a number. Color still helps when a printed review needs the success path to stand out. Set both a stroke and a label. The label survives black-and-white printing. The stroke does not.
linkStyle will not color a node. Node fills are classDef and style, which the step-by-step section already introduced. Edges and nodes are separate lists.
Comments and quoted labels
A comment starts with %% on its own line. Mermaid drops it before parsing. Use comments for the owner, the date, or the doc the chart has to match. They don't appear in the SVG, so they are a poor place for something the reader must see. Put that in a label or in the paragraph above the diagram.
flowchart TD
%% Billing deploy. On-call owns the canary check.
A["Tag v1.2.0 (prod)"] --> B{Error rate under 1%?}
B -->|Yes| C[Shift all traffic]
B -->|No| D["Roll back to v1.1.9"]Quotes are doing the work on A and D. Parentheses, slashes, colons, and question marks inside brackets are syntax unless the label is a quoted string. The id stays outside the quotes. tag["Tag v1.2.0 (prod)"] has id tag and a label with parentheses. If the label itself needs a double quote, write the entity #quot; inside the string rather than nesting " characters.
A decision can keep the question mark once it is quoted, as B is above. Unquoted B{Error rate < 1%?} is the version that sends people to the syntax guide. The < is especially unfriendly because it looks like HTML. Rephrase to "under" or quote the whole label.
Comments don't replace a missing end. They also don't hide a broken line. If you comment out an arrow, comment the whole line. A trailing %% note on a live statement still breaks some diagram types, so keep the note on the previous line.
A deploy pipeline
This chart is complete enough to paste. It uses a parent direction, three subgraphs, an inner direction, a decision, quoted labels, a comment, a dotted rollback, and one link style on the success edge. Count arrows from the top of the file. The comment and the direction lines are not edges.
flowchart LR
%% Deploy pipeline for the billing service
subgraph git [Git]
Commit["Commit on main"] --> Tag["Tag v1.2.0"]
end
subgraph ci [CI]
direction TB
Test[Unit tests] --> Image["Build image"]
Image --> Scan[Scan image]
end
subgraph ship [Ship]
direction TB
Canary[Canary] --> Check{Healthy?}
Check -->|Yes| Prod[Production]
Check -->|No| Back["Roll back"]
end
Tag --> Test
Scan --> Canary
Back -.-> Tag
linkStyle 4 stroke:#0f766e,stroke-width:2pxThe arrows in that file, in order, are Commit to Tag (0), Test to Image (1), Image to Scan (2), Canary to Check (3), Check to Prod (4), Check to Roll back (5), Tag to Test (6), Scan to Canary (7), and Roll back to Tag (8). linkStyle 4 paints the Yes branch. Insert a line above it and 4 points somewhere else. Re-count from the file.
Walk the pipeline as a reader. A commit on main gets a tag. CI tests, builds, and scans. The scan must pass before canary. Canary either takes production traffic or rolls back. The dotted edge returns to the tag so the rollback has a place to point. If your process rolls back to the previous production tag, rename Tag to the old version in the label and point the dotted edge there.
Support triage is the same shape with different owners. Swap Git, CI, and Ship for Inbox, Bot, and Human. The decision is "known issue?" instead of "healthy?". The Yes path links a public status page. The No path files a ticket. You don't need a new syntax for a new department. You need ids that match the team and labels a new hire can read out loud.
When the chart grows past two decisions, split it. One diagram for build and scan, one for canary and rollback. Link them in the README with the relative links in the GitHub guide. Export a PNG or SVG from the export guide if the host can't render the file. The source you keep is this text, not the picture.
The symbol judgment, which this tutorial assumes, is flow charts explained. The short build is make a flow chart. Starting from zero design skill is draw diagrams with Mermaid.