Mermaid Diagrams in Markdown: Flowcharts, Sequence Diagrams and More

A diagram often explains a process, an architecture or a timeline better than several paragraphs. But drawing them in a graphics editor means exporting images, storing them next to the docs and redrawing everything when something changes.

Mermaid solves this: you describe the diagram in a few lines of text inside your Markdown file, and the previewer draws it. The diagram lives in the same file, shows up in diffs and is updated as easily as a sentence. GitHub, GitLab, Obsidian, many documentation generators and Markdown Preview Editor render Mermaid out of the box.

How to add a Mermaid diagram

Create a fenced code block and set its language to mermaid:

markdown```mermaid
flowchart LR
  A[Write] --> B[Preview]
  B --> C{Ready?}
  C -- yes --> D[Export]
  C -- no --> A
```

The previewer turns this into:

The first line names the diagram type; the lines after it describe nodes and connections.

Flowcharts

Flowcharts are the diagram type people use most. The direction comes after the keyword: TD or TB (top to bottom), BT, LR (left to right) or RL.

mermaidflowchart TD
  start([Start]) --> input[/Read the file/]
  input --> valid{Is it valid?}
  valid -- Yes --> save[(Save to database)]
  valid -- No --> error[Show an error]
  error --> input

The brackets around a label define the node shape:

Connections: --> is an arrow, --- a line without an arrow, -.-> a dotted arrow and ==> a thick one. Add a label with -- text --> or -->|text|.

Group related nodes with subgraph:

mermaidflowchart LR
  subgraph Browser
    editor[Editor] --> preview[Preview]
  end
  preview --> export[HTML / PDF]

Sequence diagrams

Sequence diagrams show how participants exchange messages over time — ideal for APIs, authentication flows and user journeys.

mermaidsequenceDiagram
  participant U as User
  participant A as App
  participant S as Server
  U->>A: Click "Sign in"
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Show dashboard
  Note over A,S: The token expires after 1 hour

->> is a solid arrow (a request), -->> a dashed arrow (a response). Note over, Note left of and Note right of add comments. Use loop, alt/else and opt blocks to show repetition and branching.

Gantt charts

A Gantt chart turns a list of tasks into a timeline. Tasks can start on a date or after another task.

mermaidgantt
  title Documentation sprint
  dateFormat YYYY-MM-DD
  section Writing
  Outline      :done,   a1, 2026-10-01, 2d
  First draft  :active, a2, after a1, 4d
  section Review
  Peer review  :        a3, after a2, 3d
  Publish      :milestone, after a3, 0d

State diagrams

State diagrams describe how something moves between states — an order, a document, a UI component.

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : submit
  Review --> Draft : changes requested
  Review --> Published : approve
  Published --> [*]

Pie charts

For a quick share-of-total picture, a pie chart takes one line per slice:

mermaidpie title Where documentation time goes
  "Writing" : 45
  "Formatting" : 15
  "Keeping diagrams up to date" : 40

Mermaid also supports class diagrams, entity-relationship diagrams, mind maps, timelines, Git graphs, quadrant charts and more. The syntax for each is documented on the official Mermaid website.

Tips for readable diagrams

• Keep it small. Beyond 15–20 nodes a diagram gets hard to read. Split it into several diagrams, one per idea.
• Choose the direction deliberately. LR suits processes with few steps; TD suits hierarchies and long flows, especially on narrow screens.
• Use short IDs and readable labels. Write auth[Check the session] rather than using the label as the ID — it keeps connections short.
• Quote labels with special characters: A["Price: $5 (incl. tax)"].
• Add comments with %% at the start of a line. They are ignored when drawing.
• Preview as you type. A missing arrow or bracket breaks the whole diagram, so a live preview saves a lot of guesswork. In Markdown Preview Editor the diagram re-renders as you edit, and the Mermaid diagram button in the Advanced toolbar inserts a starter template.

Sharing documents with diagrams

When you export a document to HTML or PDF, the diagrams are included as images, so the reader doesn’t need Mermaid installed. For formulas next to your diagrams, see how to write math in Markdown, and for everything else — tables, task lists, alerts — keep the Markdown cheat sheet at hand.