How to add Mermaid diagrams to markdown

Mermaid turns plain text into flowcharts, sequence diagrams, and timelines. Because the source is text, your diagrams live in the same file as your prose and diff like any other line.

The mechanism is a fenced code block with mermaid as the language tag. Anywhere that supports it will render the block as a picture; anywhere that does not will show it as code, which is ugly but never lossy.

```mermaid
flowchart LR
  A[Draft] --> B[Review] --> C[Ship]
```

That is the entire integration. The rest is Mermaid's own syntax, which is worth knowing in outline.

Flowcharts

The most common diagram. Declare a direction — LR left-to-right, TD top-down — then describe the edges.

```mermaid
flowchart TD
  Start[User uploads file] --> Check{Valid format?}
  Check -->|yes| Parse[Parse contents]
  Check -->|no| Error[Show error]
  Parse --> Done[Save to database]
```

Node shapes come from the brackets you wrap the label in:

Syntax	Shape	Typical use
`A[Text]`	Rectangle	A step or action
`A(Text)`	Rounded	Start and end points
`A{Text}`	Diamond	A decision
`A[(Text)]`	Cylinder	A database or store
`A((Text))`	Circle	An event

Sequence diagrams

For anything involving messages between parties over time — APIs, auth flows, protocols.

```mermaid
sequenceDiagram
  participant U as User
  participant A as App
  participant S as Server

  U->>A: Click save
  A->>S: PUT /document
  S-->>A: 200 OK
  A-->>U: "Saved"
```

Solid arrows ->> are calls; dashed arrows -->> are responses. That one convention carries most of the meaning.

Other diagram types worth knowing

gantt — project timelines with dated tasks
classDiagram — UML class relationships
erDiagram — database entities and cardinality
stateDiagram-v2 — state machines
pie — simple proportion charts
gitGraph — branch and merge history

Where Mermaid renders

Support is broad but not universal, which is the main practical constraint on using it:

Platform	Renders Mermaid?
GitHub (issues, PRs, README)	Yes, natively
GitLab	Yes, natively
Notion, Obsidian	Yes
MarkNow	Yes, inline while editing
Plain `pandoc` or static site generators	Only with a plugin
Most email clients	No — export an image instead

Errors you will hit

Mermaid's parser is strict and its messages are terse. Four causes account for most failures:

Unquoted punctuation in labels. Brackets, colons, and quotes inside a label break parsing. Wrap the text: A["Save (and close)"].
Reserved words as node IDs. end is the usual culprit. Rename the ID; the visible label can still say anything.
A missing direction. flowchart alone is not enough — it needs LR, TD, RL, or BT.
Tabs for indentation. Mermaid wants spaces. An editor set to insert tabs will produce diagrams that fail for no visible reason.

Iterate somewhere with live rendering. Mermaid is a language you edit by feedback, not by reading the spec. Writing a diagram blind and pushing it to see whether the platform renders it is a slow loop and the reason most people give up on Mermaid.

Editing diagrams inline

In MarkNow, a mermaid fence renders as the diagram itself while you write, and clicking it opens the source next to a live preview. You edit the text, watch the picture update, and close — the document keeps the fence exactly as a fence, so the file stays portable to GitHub or anywhere else that renders Mermaid.

It runs in the browser with no signup, so you can paste a broken diagram in and find the syntax error in a few seconds rather than a few pushes.