# Diagrams

> Draw flowcharts, sequence diagrams, and other Mermaid diagrams from text in a code fence.

Write a [Mermaid](https://mermaid.js.org) diagram in a code fence with the language `mermaid`, and the published page draws it. The diagram lives in your page as text, so it diffs and reviews like the rest of your docs.

```mermaid
flowchart LR
  A[Write MDX] --> B[Push to GitHub]
  B --> C{Build passes?}
  C -->|Yes| D[Site is live]
  C -->|No| E[Previous version stays up]
```

````mdx
```mermaid
flowchart LR
  A[Write MDX] --> B[Push to GitHub]
  B --> C{Build passes?}
  C -->|Yes| D[Site is live]
  C -->|No| E[Previous version stays up]
```
````

Diagrams follow the reader's light or dark theme and redraw when they switch.

## Diagram types

Any diagram Mermaid supports works, for example:

| Diagram | First line |
|---------|------------|
| Flowchart | `flowchart LR` or `graph TD` |
| Sequence diagram | `sequenceDiagram` |
| Class diagram | `classDiagram` |
| State diagram | `stateDiagram-v2` |
| Entity relationship | `erDiagram` |
| Gantt chart | `gantt` |
| Pie chart | `pie` |

```mermaid
sequenceDiagram
  participant App
  participant API
  App->>API: POST /tokens
  API-->>App: 201 Created
```

````mdx
```mermaid
sequenceDiagram
  participant App
  participant API
  App->>API: POST /tokens
  API-->>App: 201 Created
```
````

## In tabs and code groups

A diagram works anywhere a code block does, including inside [Tabs](https://docs.typemark.dev/components/tabs) and [Code groups](https://docs.typemark.dev/components/code-blocks#code-groups). In a code group, the label after `mermaid` names the tab.

````mdx
<CodeGroup>
```mermaid Flow
flowchart LR
  Request --> Response
```

```bash curl
curl https://api.acme.com/health
```
</CodeGroup>
````

## When a diagram has an error

If Mermaid can't read a diagram, the page shows its source as a code block with a short note naming the error, such as "Parse error on line 2". The rest of the page is unaffected. Fix the diagram and publish again.

Readers without JavaScript, and AI tools reading your page as Markdown or through `llms.txt`, get the diagram's source.

## Security

Diagrams are drawn in the reader's browser with Mermaid's strict security level: labels can't contain scripts, and click actions in diagrams are turned off.

## In the visual editor

A Mermaid block stays a code block you type into, with the diagram drawn underneath. The drawing updates a moment after you stop typing, and shows the error if the diagram has one. To start one, insert a **Code block** and pick **Mermaid** from the language picker.
