How to Create a Flowchart from Text Using Mermaid (Free Browser Tutorial)

Drawing flowcharts by dragging boxes around is slow, and the result is hard to update or review in a pull request. With Mermaid, you write the flowchart as text and the layout is computed for you. The text lives next to your code, diffs cleanly and renders on GitHub, GitLab, Notion and Obsidian.

In this tutorial we'll build a real flowchart step by step: a password-reset flow, with a decision, a loop and a database step.

Disclosure: I built PasteZap, the free browser editor I use for the live preview below. Any Mermaid editor works the same way, since the syntax is standard Mermaid 11.

1. The smallest possible flowchart

Every Mermaid flowchart starts with flowchart and a direction:

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

• TD (or TB) means top to bottom. You can also use LR (left to right), RL and BT.
• A, B and C are IDs. The text in brackets is the label shown in the box.
• --> draws an arrow.

Once a node is declared, refer to it by its ID only: B --> C.

2. Pick the right shape for each step

The brackets around a label decide the shape. These are the ones you'll use most:

Code	Shape	Typical use
A[Text]	Rectangle	Process step
A(Text)	Rounded rectangle	Softer process step
A([Text])	Stadium	Start / end
A{Text}	Diamond	Decision
A[/Text/]	Parallelogram	Input / output
A[(Text)]	Cylinder	Database
A[[Text]]	Subroutine	Call to another process
A((Text))	Circle	Connector

3. Add decisions with labelled arrows

A decision is a diamond with one arrow per answer. Put the answer between pipes, right after the arrow:

flowchart TD
    C{Account exists?}
    C -->|Yes| D[Create one-time token]
    C -->|No| E[Show the same confirmation message]

Showing the same message whether or not the account exists is deliberate: it stops attackers from using the form to find out which emails are registered. Flowcharts are a good place to make that kind of rule visible.

4. The complete password-reset flow

Here is the full example. It has a decision, a retry loop when the link expires and another loop when the new password is rejected:

flowchart TD
    A([User clicks Forgot password]) --> B[/Enter email address/]
    B --> C{Account exists?}
    C -->|Yes| D[Create one-time token]
    C -->|No| E[Show the same confirmation message]
    D --> F[Send reset email]
    F --> E
    E --> G{Link opened within 30 min?}
    G -->|No| H[Token expires]
    H --> B
    G -->|Yes| I[/Enter new password/]
    I --> J{Meets password policy?}
    J -->|No| I
    J -->|Yes| K[(Update users table)]
    K --> L([Done])

📷 [Upload the exported PNG here with the image button of the editor]

Loops need no special syntax: H --> B and J -->|No| I simply point back to an earlier step, and Mermaid routes the arrow for you.

You can open this exact diagram in a live editor: the whole diagram is stored in the part of the link after #, which browsers don't send to the server.

5. Change the arrow style

Different arrows help separate the main path from exceptions:

Code	Arrow
-->	Solid arrow
-.->	Dotted arrow (optional or async step)
==>	Thick arrow (main path)
---	Line without arrowhead
--o	Circle end
--x	Cross end

For example, make the happy path stand out with C ==>|Yes| D.

6. Common errors and how to fix them

• end breaks the diagram. A node labelled with the lowercase word end closes a block in Mermaid's parser. Write End, Done or wrap it in quotes: Z["end"].
• Special characters in labels. Parentheses, brackets or quotes inside a label confuse the parser. Wrap the label in double quotes: A["Check (optional) fields"].
• Reusing an ID with a new label. A[Start] and later A[Begin] refer to the same node; the last label wins. Use a new ID for a new step.
• Diagram too wide. Switch TD to LR (or the other way around) before trying anything more complex.

7. Put it in your README

GitHub and GitLab render Mermaid code blocks directly. Paste the diagram in a fenced code block whose language is mermaid (three backticks followed by the word mermaid), and it appears as a picture in the README, issue or pull request.

For slides or docs that don't support Mermaid, export the flowchart as SVG (sharp at any size) or PNG.

Try it

Write the flow you're working on right now as text: a signup, a deployment, an order process. If you'd like a live preview while you type, PasteZap's Flowchart Maker is free, needs no account and renders the diagram in your browser. It also has a form to add steps one by one if you don't want to write the syntax yet.

What flows do you document with Mermaid? I'd be glad to hear which diagram types you'd like covered next.