Mermaid flowcharts

A Mermaid flowchart turns a few lines of text into a diagram of boxes and arrows. You write it inside a Markdown file, in a fenced code block marked mermaid. Tools that support Mermaid draw the diagram. Tools that don’t still show readable text. This page covers the parts you need most: direction, node shapes, links, labels and subgraphs.

The smallest flowchart

Every flowchart starts with the keyword flowchart and a direction. After that, each line describes nodes and the links between them.

flowchart TD
    A[Write draft] --> B[Review]
    B --> C[Publish]

A, B and C are node IDs. The text in brackets is the label people see. Once a node has a label, you can refer to it by its ID alone.

Directions

The direction comes right after flowchart:

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

Left to right often fits better on wide screens and in documentation.

flowchart LR
    Idea --> Plan --> Build --> Ship

You can chain several links on one line, as shown above. Plain words without brackets work as both ID and label.

Node shapes

The brackets around a label set the shape of the node.

flowchart LR
    A[Rectangle] --> B(Rounded)
    B --> C([Stadium])
    C --> D[(Database)]
    D --> E((Circle))
    E --> F{Decision}
    F --> G{{Hexagon}}
    G --> H[/Parallelogram/]
    H --> I>Flag]

A common convention: rounded or stadium shapes for start and end, rectangles for steps, diamonds for decisions, and the cylinder for data stores.

Mermaid 11 also has a newer shape syntax with many more shapes. You write the node ID, then @{ } with a shape name and a label.

flowchart LR
    A@{ shape: doc, label: "Report" } --> B@{ shape: cyl, label: "Archive" }

The bracket shapes above are shorter to type and work in older Mermaid versions too.

Links and arrows

The link between two nodes can look different:

flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E --o F
    F --x G
    G <--> H

• --> is a normal arrow.
• --- is a line without an arrowhead.
• -.-> is a dotted arrow.
• ==> is a thick arrow.
• --o and --x end in a circle or a cross.
• <--> points both ways.

Add extra dashes to make a link longer, for example --->. This pushes the target node further away and can help untangle a crowded layout.

Edge labels

Labels on links explain why the flow goes one way or another. There are two ways to write them: between pipes after the arrow, or in the middle of the arrow.

flowchart TD
    A[Pull request] --> B{Tests pass?}
    B -->|Yes| C[Merge]
    B -- No --> D[Fix and push]
    D --> B

Both forms give the same result. Pick one and stay with it in a file.

Subgraphs

A subgraph groups nodes in a labelled box. Start it with subgraph, give it an ID and a title, and close it with end.

flowchart LR
    subgraph client [Mac app]
        direction TB
        UI[Window] --> Parser[Markdown parser]
    end
    subgraph disk [File system]
        File[(notes.md)]
    end
    disk --> client

The last line links one subgraph to the other by ID. You can set a direction inside a subgraph with direction. Mermaid ignores that direction if a node inside the subgraph links to a node outside it, so link the subgraphs themselves when you need both. Subgraphs can also be nested.

Comments and special characters

Lines that start with %% are comments. Mermaid skips them.

If a label contains brackets, quotes or other symbols, put the label in double quotes. Mermaid then treats it as plain text.

flowchart TD
    %% Labels with symbols need quotes
    A["Save (as draft)"] --> B["Send to: team@example.com"]

Avoid the lowercase word end as a node ID. It closes subgraphs and breaks the diagram. Also be careful when an ID starts with o or x right after a link, like A---oB. Mermaid reads that as a circle or cross arrowhead. Add a space, or capitalise the ID.

Tips for readable flowcharts

• Keep one idea per diagram. Split large flows into several smaller ones.
• Use short labels. Put details in the text around the diagram.
• Give nodes meaningful IDs, like review instead of B. This makes the source easier to edit later.
• Choose LR for long, simple chains and TD for flows with many branches.

Viewing flowcharts on a Mac

Mermaid is plain text, so any editor can open the file. To see the drawn diagram, you need a tool that renders Mermaid, such as GitHub, many editor preview panes, or a Markdown viewer. Markko Pro renders Mermaid diagrams in its window and in Quick Look, so you can check a flowchart by pressing Space on the file in Finder.

The full reference lives in the official Mermaid documentation at mermaid.js.org.

FAQ

Related