MarkdownPaper Open reader

Guide

Mermaid diagrams in Markdown

Mermaid draws a diagram from a few lines of text. Write it in a code block marked mermaid, and apps that support it show the picture instead of the code.

You write

```mermaid
flowchart LR
  A[Write] --> B[Review]
  B --> C[Publish]
```

You see

Because the diagram is text, it lives in the same file as the words, changes show up in version control line by line, and an AI assistant can write one for you.

3 min read9 sectionsUpdated 1 Oct 2026

On this page

Flowchart

Start with flowchart and a direction: TD for top down, LR for left to right. Each node has an id and a label. Arrows join the ids.

You write

```mermaid
flowchart TD
  start([Order placed]) --> paid{Paid?}
  paid -->|Yes| ship[Ship it]
  paid -->|No| remind[Send a reminder]
  remind --> paid
```

You see

WriteShape
id[Text]Rectangle
id(Text)Rounded rectangle
id([Text])Pill
id{Text}Diamond, a decision
id((Text))Circle

--> is an arrow, --- a plain line, -.-> a dotted arrow, and -->|label| puts text on the arrow.

Sequence diagram

For messages passed between people or systems, in order.

You write

```mermaid
sequenceDiagram
  Browser->>Server: Log in
  Server->>Database: Check password
  Database-->>Server: OK
  Server-->>Browser: Welcome
```

You see

->> is a solid arrow, -->> a dashed reply.

Gantt chart

For a plan over time. Each task has a name, an id or a start, and a length.

You write

```mermaid
gantt
  dateFormat YYYY-MM-DD
  section Build
  Design     :a1, 2026-01-05, 5d
  Code       :a2, after a1, 10d
  section Ship
  Test       :after a2, 4d
```

You see

Pie chart

You write

```mermaid
pie title Where the time went
  "Writing" : 50
  "Editing" : 30
  "Meetings" : 20
```

You see

The numbers do not need to add up to 100. Mermaid works out the shares.

Other diagrams

Mermaid also draws class diagrams, state diagrams, entity relationship diagrams, mind maps, timelines, user journeys and Git graphs. Each starts with its own keyword, such as classDiagram or mindmap, and the Mermaid documentation has the syntax for each.

Where Mermaid renders

AppMermaid
GitHubYes, in files, issues and comments
GitLabYes
MarkdownPaperYes
ObsidianYes
VS Code previewWith an extension

Where Mermaid is not supported, the block shows as code, so the file still reads.

Common problems

  • The code shows instead of a diagram. The fence is not marked mermaid, or the app does not support it.
  • "Syntax error" instead of a diagram. Often a label with brackets or quotes in it. Wrap the label in double quotes: A["Step (1)"].
  • A word breaks the diagram. end is a keyword in flowcharts. Write it with a capital, End, or put it in quotes.

Questions

How do I add a diagram to a Markdown file?

Write the diagram in Mermaid inside a code block marked mermaid. Apps that support Mermaid show it as a picture.

Does GitHub render Mermaid diagrams?

Yes. A mermaid code block in a README, an issue or a comment shows as a diagram.

How do I view a Mermaid diagram that an AI wrote?

Paste the whole answer into a Markdown reader that supports Mermaid, such as MarkdownPaper. The diagram is drawn on the page with the rest of the text.

Next