Mermaid Flowcharts and Sequence Diagrams: A Practical Guide

Mermaid turns a few lines of text into a diagram. You write A --> B, and a box with an arrow to another box appears. Because the source is plain text, it lives happily in a README, a pull request or a wiki page, and a change to the diagram shows up in a diff like any other change. GitHub renders it too: put the code in a fenced block marked mermaid and it draws in issues, pull requests, discussions, wikis and Markdown files.

Most people need two kinds of diagram: flowcharts, for steps and decisions, and sequence diagrams, for who sends what to whom and in which order. This guide covers both, then the handful of mistakes behind most "Syntax error" messages.

Every example below parses in Mermaid 11. Paste any of them into the Mermaid editor to see it drawn as you edit.

Flowcharts: the first line sets the direction

Every Mermaid diagram starts by declaring its type. For a flowchart, that's flowchart (the older graph keyword still works) followed by a direction:

Code	Direction
TB or TD	Top to bottom
BT	Bottom to top
LR	Left to right
RL	Right to left

Use TD for processes read like a recipe and in narrow doc columns; use LR for pipelines and on slides.

Nodes: an id, then a label in a shape

A node has an id (what you use to connect it) and, optionally, text in brackets. The brackets pick the shape:

You write	Shape	Good for
A[Text]	Rectangle	An ordinary step
A(Text)	Rounded rectangle	A softer step
A([Text])	Stadium	Start and finish
A{Text}	Diamond	A yes/no decision
A[(Text)]	Cylinder	A database
A[[Text]]	Subroutine	A step that's its own process
A((Text))	Circle	A connector or event
A{{Text}}	Hexagon	A preparation step

Once a node exists, use its id alone. B later in the diagram is the same box, so you only write its label once.

Here's a checkout flow using four of those shapes:

flowchart TD
    A([Customer clicks Pay]) --> B{Card valid?}
    B -->|Yes| C[Charge the card]
    B -->|No| D[Show an error]
    D --> A
    C --> E[(Orders database)]
    C --> F[[Send receipt]]

Since Mermaid 11.3 there's also a longer form, A@{ shape: rect }, which unlocks dozens of extra shapes. The bracket forms above are shorter and cover most diagrams.

Arrows and labels

The link between two nodes sets the line style:

Link	Looks like
A --> B	Solid line with an arrowhead
A --- B	Solid line, no arrowhead
A -.-> B	Dotted line with an arrowhead
A ==> B	Thick line with an arrowhead

To put words on a link, use either A -- Yes --> B or A -->|Yes| B. They draw the same thing; the pipe form is easier to scan in a long file.

You can chain links on one line (A --> B --> C), and & connects several nodes at once: A --> B & C draws two arrows. To make one link longer, add a dash: A ---> B.

Subgraphs group related nodes

A subgraph draws a labelled box around part of the diagram. It opens with subgraph and a title and closes with end:

flowchart LR
    subgraph Browser
        UI[Checkout page]
    end
    subgraph Server
        API[Payments API] --> DB[(Orders)]
    end
    UI -->|POST /pay| API

Links can cross subgraph borders freely, as UI --> API does here. If the title needs spaces and you want a short id, write subgraph srv [Payment servers].

Sequence diagrams: participants and messages

A sequence diagram starts with sequenceDiagram. Participants appear in the order you mention them, so declare them up front if the order matters. participant draws a box and actor draws a stick figure, and as gives a short id a readable name:

sequenceDiagram
    autonumber
    actor U as Customer
    participant W as Web app
    participant P as Payment provider
    U->>+W: Click Pay
    W->>+P: Charge card
    P-->>-W: Result
    alt card accepted
        W-->>U: Show the receipt
        W-)U: Email the receipt
    else card declined
        W-->>U: Ask for another card
    end
    deactivate W
    Note over W,P: Charges carry an idempotency key, so a retry never charges twice

The arrow says what kind of message it is:

Arrow	Meaning
->>	Solid line with an arrowhead: a call or request
-->>	Dotted line with an arrowhead: the reply
-> / -->	Solid or dotted line without an arrowhead
-x / --x	Line ending in a cross: a message that fails or is lost
-) / --)	Open arrowhead: an asynchronous message, fire and forget

The convention that keeps sequence diagrams readable is solid for requests, dotted for responses. A reader can then follow a conversation without reading the labels.

Activations

An activation bar shows how long a participant is busy. Write activate W and deactivate W on their own lines, or use the shorthand: a + after the arrow activates the receiver (U->>+W), and a - deactivates the sender of the reply (P-->>-W). Every activation needs exactly one matching deactivation.

Blocks: alt, opt, loop and par

Blocks frame part of the conversation, and each one closes with end:

• alt condition … else other condition … end for either-or paths, like the accepted and declined branches above.
• opt condition … end for something that only sometimes happens.
• loop description … end for repetition, such as loop Every 30 seconds.
• par first … and second … end for things that happen at the same time.

Notes and numbering

Note right of P: text and Note left of U: text sit beside one participant; Note over W,P: text spans two. autonumber on its own line numbers every message, which helps when you're discussing step 7 in a review.

The errors that break most diagrams

Mermaid is strict. The syntax reference puts it plainly: unknown words and misspellings break a diagram, while bad configuration values tend to fail silently. These are the mistakes worth knowing by sight.

1. A misspelled first line. flowchar TD gets you "No diagram type detected". Check the keyword before anything else.

2. Lowercase end as a node. B --> end fails, because end is the keyword that closes a subgraph. Capitalise it (End), or give the node a different id and put the word in the label: B --> F[end]. The sequence diagram docs give the same warning; if a message or note trips on it, wrap the word in quotes or brackets.

3. Brackets or parentheses inside a label. A[Call f(x)] fails because Mermaid reads ( as the start of a new shape. Quote the label: A["Call f(x)"]. Quotes are the general fix for any label with punctuation.

4. Quotes inside a quoted label. A["He said "hi""] parses, but the inner quotes vanish from the box. Use the entity code instead: A["He said #quot;hi#quot;"]. Mermaid accepts numeric codes (#35; is #) and HTML entity names.

5. A semicolon in a sequence message. A->>B: wait; retry fails, because a semicolon can end a statement just like a new line. Write #59; where you want the semicolon: A->>B: wait#59; retry.

6. A node id starting with o or x right after a link. This one doesn't raise an error; it quietly draws the wrong thing. In dev---ops, Mermaid reads ---o as a link with a circle on the end and creates a node called ps. Add a space (dev--- ops) or capitalise (dev---Ops).

7. A single-dash arrow in a flowchart. A -> B is a sequence diagram arrow. Flowcharts need at least two dashes: A --> B.

8. Spaces in an id. Start here --> B fails. Ids are single words; put the spaces in the label: S[Start here] --> B.

9. An unbalanced activation. Deactivating a participant that isn't active stops the diagram with "Trying to inactivate an inactive participant". Count your + and - signs.

What doesn't matter: indentation inside the diagram. Mermaid ignores leading spaces, so indent blocks and subgraphs however reads best. YAML front-matter at the very top (for a title or config) is the exception, because YAML needs consistent indentation.

Two habits prevent most errors. Add one or two lines at a time and watch the preview, so you know exactly which line broke it. And use %% for comments, on their own line, to leave yourself notes such as %% retry path added after the March outage. Avoid curly braces inside comments, which the syntax reference warns can confuse the parser.

Describe a diagram in plain words with on-device AI

Writing the first draft is the slow part, especially for a diagram type you rarely use. The Mermaid editor has an AI button that does three things:

• Describe: write what you want in a sentence or two ("how a support ticket goes from new to closed, with a step back when the customer replies"), pick a type if you like (flowchart, sequence, state, database ER or mind map; Auto lets the model choose), and it drafts the Mermaid code.
• Explain: it reads the open diagram and writes a plain-language summary, which you can add to the code as %% comments for the next person.
• Fix error: when the Problems bar shows a line that won't parse, Fix with AI proposes a corrected version.

The editor checks every suggestion with Mermaid's own parser before showing it. If the first draft doesn't parse, it asks the model to repair it once; if that still fails, it tells you and changes nothing. You see a small preview first, then choose Replace diagram, New diagram or Copy, and an applied change can be undone like any edit.

By default this uses your browser's built-in model. In Chrome that's Gemini Nano, which runs on your own computer, so your description and diagram never leave the device. Google's documentation lists the requirements: a desktop operating system (Windows 10 or 11, macOS 13 or later, Linux, or a Chromebook Plus), at least 22 GB free on the drive with your Chrome profile, and either a GPU with more than 4 GB of memory or 16 GB of RAM with four or more CPU cores. The model downloads the first time a site uses it; after that it works offline. If your browser doesn't have it, the AI button stays hidden, or you can add a key for a hosted model in Settings → AI, in which case the text goes from your browser straight to the provider you picked. Our guide to what Chrome's built-in AI can and can't do covers when each makes sense.

A small on-device model is good at first drafts of short diagrams. Read what it gives you: it can get the shape right and a detail wrong. Without AI, Copy for AI in the Problems bar copies the error and your code together, ready to paste into any chat assistant.

Where to keep your diagrams

A diagram is most useful next to the words that explain it. The Markdown editor renders Mermaid blocks inside its pages, so a design note and its flowchart sit together. In the Mermaid editor, Export copies the image for Google Docs or Slack, downloads PNG, SVG or PDF, or copies the code as a Markdown block for GitHub. If GitHub draws something differently from your editor, put the single word info in a Mermaid block there: GitHub's docs suggest it to show which Mermaid version they run.

The short version

• Start with flowchart TD or flowchart LR, or with sequenceDiagram.
• Flowchart nodes are id[label]; the brackets choose the shape. Link with -->, label with -->|text|.
• In sequence diagrams, use ->> for requests and -->> for replies, + and - for activations, and alt, opt, loop and par blocks that each close with end.
• Quote labels with punctuation, never use lowercase end as a node, write #59; for a semicolon in a message, and watch for ids starting with o or x after a link.
• Build up a line or two at a time, and let the preview tell you which line broke.

Sources

• Mermaid documentation. Flowcharts: basic syntax. Directions, node shapes, links, subgraphs, the end and o/x warnings, entity codes, comments.
• Mermaid documentation. Sequence diagrams. Participants, actors and aliases, arrow types, activations, notes, alt/opt/loop/par blocks, autonumber, the #59; semicolon code.
• Mermaid documentation. Diagram syntax reference. Diagram type declaration, unknown words breaking diagrams, braces in comments, YAML front-matter indentation.
• GitHub Docs. Creating diagrams. Mermaid rendering in issues, pull requests, discussions, wikis and Markdown files, and the info version check.
• Chrome for Developers. The Prompt API. Gemini Nano running on-device, hardware and storage requirements, first-use download.