Mermaid Diagrams in Markdown: Syntax and Examples

The mermaid code block

A Mermaid diagram lives in a fenced code block. A fence is three backticks. After the opening fence, write mermaid as the language:

```mermaid
flowchart LR
    A --> B
```

The first line inside the block says which kind of diagram it is. Here it is flowchart LR. Everything after that line describes the diagram.

Lines that start with %% are comments. The reader ignores them.

Example 1: a flowchart with a decision

```mermaid
flowchart TD
    Start[Write the note] --> Check{Is it clear?}
    Check -->|Yes| Publish[Share it]
    Check -->|No| Edit[Rewrite it]
    Edit --> Check
```

How to read it:

flowchart TD means top to down. Use LR for left to right. The word graph also works in place of flowchart.
Start[Write the note] makes a box. Start is the short name. The text in brackets is the label.
Curly brackets { } make a decision shape, a diamond.
--> draws an arrow. Text between pipes, like |Yes|, labels the arrow.

Example 2: a sequence diagram

A sequence diagram shows who talks to whom, in order.

```mermaid
sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Open the page
    S-->>U: Send the page
    U->>S: Log in
    S-->>U: Welcome
```

participant U as User creates a column named User. The short name is U.
->> is a solid arrow. -->> is a dotted arrow, often used for replies.
The text after the colon is the message.
The messages are drawn from top to bottom, in the order you write them.

Example 3: a pie chart

```mermaid
pie title Time spent on a project
    "Writing" : 40
    "Reading" : 25
    "Meetings" : 15
    "Other" : 20
```

Each slice is a label in quotes, a colon and a number. The number must be above zero.

Other diagram types

Mermaid can draw many more kinds. The common ones:

Gantt chart: tasks on a timeline.
Class diagram: classes in code and how they connect.
State diagram: the states of a thing and how it moves between them.
Entity relationship diagram: database tables and links.
User journey: the steps a person takes.
Mindmap: ideas branching from one centre.
Timeline: events in order of date.
Git graph: branches and commits.

Each type has its own first word and its own rules. The Mermaid documentation has a page for each one.

Where Mermaid diagrams are drawn

GitHub draws Mermaid blocks in Markdown files, issues, discussions, pull requests and wikis. You only need the mermaid code block. Many Markdown editors and notes apps support Mermaid too, but not all of them.

When a reader does not support Mermaid, it usually treats the block like any other code. You see the text you wrote, not a picture. Nothing is lost. It is just not drawn.

Common mistakes

A small typo breaks the whole diagram. Unknown or misspelled keywords stop it from drawing. If you see an error or plain text, check the first line and the arrows first.
Special characters in labels. Brackets, parentheses and similar characters can confuse the parser. Put the label in quotes: A["Save (draft)"].
The word end in a flowchart. In lowercase, end breaks a flowchart. Write End or END, or put the word in quotes. It can also cause trouble in sequence diagrams.
Wrong fence. The language after the backticks must be mermaid. Without it, the reader sees a plain code block.

Indentation is not needed. Most people indent the lines inside a diagram only because it is easier to read.

AI chats and agents write Mermaid

AI chats and coding agents often put Mermaid in plans, specs and design notes. A flowchart is a quick way to show steps. A sequence diagram shows how parts of a system talk.

If a chat gives you a diagram, copy the whole code block, including the fences, into your Markdown file. If the diagram does not draw, check it against the mistakes above. Short labels and one idea per diagram make the text easier to fix.

Reading Mermaid diagrams

PilcrowMD draws Mermaid diagrams on Android and on Mac, with no internet needed. On Android, tap a diagram to see it full screen. On Mac, Quick Look, Compare and PDF show the code block instead of the picture.

Common questions

Do I need to install anything to write Mermaid? No. You write plain text in a code block. You only need a reader that draws it.

Why do I see code instead of a diagram? Either the reader does not support Mermaid, or the diagram has a syntax error. Check that the block starts with mermaid and that the first line names a real diagram type.

Can I change how a diagram looks? Yes. Mermaid has options for colours, shapes and layout. Start with the defaults. They are enough for most notes.

Also on Mac: PilcrowMD for Mac (beta)

Mermaid diagrams in Markdown