How to write a Mermaid flowchart:a direction, nodes and arrows.

Direction

The first line names the diagram type and the direction. flowchart and the older graph both work.

• TD or TB: top to bottom
• BT: bottom to top
• LR: left to right
• RL: right to left

Pick LR for a short process that fits the width of a page and TD for a longer one.

Node shapes

A node is an id, optionally followed by its text in brackets. The brackets pick the shape:

flowchart LR
    a[Rectangle]
    b(Rounded)
    c([Stadium])
    d[[Subroutine]]
    e[(Database)]
    f((Circle))
    g{Decision}
    h{{Hexagon}}
    i[/Parallelogram/]

A node with no brackets just shows its id. You can mention a node again later by its id alone, so the shape and the text are written once.

Links and labels

Links join two nodes. The shape of the arrow shows the kind of connection:

flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -->|label| F
    F -- text --> G

• --> an arrow, --- a line with no arrowhead
• -.-> a dotted arrow, ==> a thick one
• -->|label| or -- label --> puts text on the link
• A --> B & C links one node to several, and A --> B --> C chains links

Add dashes to make a link longer, for example ---->, when a node needs more room.

Subgraphs

A subgraph groups nodes in a labeled box. It starts with subgraph and ends with end:

flowchart TD
    subgraph client [Client]
        A[Browser] --> B[App]
    end
    subgraph server [Server]
        C[API] --> D[(Database)]
    end
    B --> C

The word in brackets is the title, and the word before it is the id you can link to. A subgraph can have its own direction LR line inside, though the direction is ignored if a node inside links to something outside.

A complete example

Putting it together, here is a small release process with a decision, a loop back and a grouped step:

flowchart TD
    A([Start]) --> B[Write the change]
    B --> C{Tests pass?}
    C -->|No| B
    C -->|Yes| D[Open a pull request]
    subgraph review [Review]
        D --> E{Approved?}
        E -->|No| B
    end
    E -->|Yes| F[(Merge)]

Read it from the top: the stadium shape marks the start, the diamonds are questions, labeled arrows are the answers, and the box around two nodes is the review. Naming each decision as a question and each arrow as its answer makes a flowchart readable without explanation.

Comments and styles

A line that starts with %% is a comment and is not drawn. To color nodes, define a class and apply it:

flowchart TD
    %% the happy path
    A[Start]:::good --> B[Done]:::good
    classDef good fill:#d4f4dd,stroke:#2d7a46

Keep styling light. Most flowcharts read better with fewer colors, and styles can look different in light and dark themes.

Common mistakes

• The word end in lowercase as a node text breaks the diagram. Write End or quote the text.
• A node id that starts with o or x right after a link, such as A---oB, is read as a circle or cross link. Add a space or capitalize it.
• Special characters in a label. Brackets, parentheses and colons need double quotes: A["Save (draft)"].
• No first line. Without flowchart TD nothing is drawn.
• Too many nodes. A flowchart with thirty boxes is hard to read. Split it, or use subgraphs.

When a diagram fails, Mermaid shows an error message, and the text stays in your file to fix.

Drawing it

GitHub draws Mermaid blocks in Markdown files, and so does DotMD: offline, in the light or dark theme to match the page. In the editor, Insert → Diagram puts a working flowchart into the document and the preview redraws as you type. The same guide covers sequence, class, state, ER and Gantt diagrams. For the fence syntax itself, see code blocks in Markdown.

Questions about Mermaid flowcharts

More questions