---
title: "Mermaid diagrams in Markdown"
author: Pedro Thomaz
source: https://coffeetext.app/blog/mermaid-diagrams-markdown
---

# Mermaid diagrams in Markdown

> Checked November 2026 against [GitHub's docs on diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams), the [Mermaid docs](https://mermaid.js.org/intro/), [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) and [VS Code's Markdown docs](https://code.visualstudio.com/docs/languages/markdown). Coffee isn't affiliated with any of them.

[Mermaid](https://mermaid.js.org/intro/) is a way of describing a diagram in text, and Markdown carries it in a fenced code block. Open the block with three backticks followed by the word `mermaid`, write the diagram, and close it with three backticks. An app or site that supports Mermaid draws the picture. Anywhere else, the reader sees the text, which is short enough to make sense on its own.

## Why write diagrams as text

A diagram drawn in a graphics app is a separate file you have to export, place and redraw when something changes. A Mermaid diagram lives in the note, beside the writing it explains. Changing a step means editing a line. It works with version control, search and AI tools like any other text, and nothing is lost if the app you use now stops drawing it.

The trade-off is control. Mermaid lays the diagram out for you, so you describe what connects to what, not where each box sits.

## Flowcharts

A flowchart starts with `flowchart` (or the older `graph`) and a direction: `TD` for top down, `LR` for left to right. Then one line per connection:

```
flowchart LR
    A[Draft] --> B{Approved?}
    B -->|Yes| C[Publish]
    B -->|No| A
```

Inside the block, that draws three arrows between three shapes. The letters are names you use to refer to each shape. The brackets set the shape: `[ ]` for a box, `{ }` for a diamond, `( )` for rounded corners. `-->` draws an arrow, and text between pipes, as in `|Yes|`, labels it.

## Pie charts

A pie chart takes a title and one line per slice, with the label in quotes and a number after a colon:

```
pie title Where the week went
    "Writing" : 18
    "Meetings" : 9
    "Email" : 6
    "Research" : 7
```

The numbers don't have to add up to 100. Mermaid works out each slice's share of the total.

## Sequence diagrams

A sequence diagram shows messages passing between people or systems, top to bottom in time order:

```
sequenceDiagram
    Writer->>Editor: Here's the draft
    Editor-->>Writer: Two comments
    Writer->>Editor: Fixed, please check
```

`->>` is a solid arrow and `-->>` a dashed one, often used for replies. Each name becomes a column, in the order it first appears.

Mermaid has many more kinds, including Gantt charts, class, state and entity relationship diagrams, and mind maps. The [Mermaid docs](https://mermaid.js.org/intro/) cover each one, and the Mermaid Live Editor lets you try the syntax in a browser.

## Where Mermaid renders

- **GitHub** draws a `mermaid` code block [as a diagram](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) in Markdown files, issues, discussions, pull requests and wikis. It notes that what's supported depends on its Mermaid version, and that putting `info` in a block shows which version that is.
- **VS Code's** built-in preview [renders Mermaid](https://code.visualstudio.com/docs/languages/markdown) in `mermaid` code blocks.
- **Many Markdown editors and note apps** draw it, sometimes only for some diagram kinds or after you turn it on.
- **Plain text editors and most email clients** show the code.

Because support varies, write the code so it reads well as text too: short, clear labels and one connection per line.

## Exporting a diagram

If you need the diagram as an image, for a slide or a document that can't run Mermaid, you have a few routes:

- **[Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)** turns a diagram file into SVG or PNG from Terminal. Install it with `npm install -g @mermaid-js/mermaid-cli`, then run `mmdc -i diagram.mmd -o diagram.svg`. Give it a Markdown file instead and it renders each `mermaid` block and writes a copy of the file that links to the images.
- **An editor that exports** with the diagram drawn, as a PDF, HTML page or Word file.
- **A screenshot**, which is quick and fine for something informal.

SVG stays sharp at any size, so prefer it to PNG where the destination accepts it.

## In Coffee

Coffee draws three kinds of Mermaid diagram: flowcharts written with `flowchart` or `graph`, pie charts, and sequence diagrams. The picture appears under the code block as you type, drawn by Coffee itself, and it's included when you export to PDF, HTML, Word or EPUB, so the diagram reaches a [PDF](https://coffeetext.app/blog/markdown-to-pdf-mac) or an [e-book](https://coffeetext.app/blog/markdown-to-epub-mac) without a separate image.

Other kinds, such as Gantt charts and class or state diagrams, stay as code in Coffee. That's worth knowing before you rely on one. The file keeps exactly what you wrote either way, so GitHub or another tool can still draw those kinds later.

Coffee also draws `$$` maths blocks as formulas. See [writing maths in Markdown](https://coffeetext.app/blog/math-equations-in-markdown).

## Questions

### How do I add a Mermaid diagram to Markdown?

Put the diagram in a fenced code block whose opening line is three backticks and the word mermaid. Apps and sites that support Mermaid draw it, and others show the code.

### Does GitHub support Mermaid?

Yes. GitHub draws Mermaid code blocks in Markdown files, issues, discussions, pull requests and wikis. Which syntax works depends on the Mermaid version GitHub uses.

### How do I export a Mermaid diagram as an image?

Mermaid CLI converts a diagram to SVG or PNG from Terminal. An editor that draws Mermaid can also include it in a PDF, HTML or Word export.

### Which Mermaid diagrams does Coffee draw?

Flowcharts, pie charts and sequence diagrams, in the editor and in PDF, HTML, Word and EPUB exports. Other kinds stay as code.

---

Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt