# Mermaid diagrams in documents

Source: https://versodocs.com/docs/diagrams

A **Mermaid diagram** block stores the diagram as text and renders it as a picture. Because the source is the content, a proposal that changes a diagram shows a line-by-line diff of the code, just like any other edit.

## Add a diagram

1. Type **/** in an empty line and pick **Diagram (Mermaid)** (or search "flowchart"), or use **Insert → Diagram (Mermaid)** in the toolbar.
2. Edit the source on the left; the preview on the right updates as you type. Press **Done** or **Escape** to go back to the document.
3. Click a diagram (or press **Edit**) to change it later.

```mermaid
flowchart LR
  A[Draft] --> B{Review}
  B -->|Approved| C[Published]
  B -->|Changes| A
```

Any Mermaid diagram type works: flowchart, sequence, class, state, entity relationship, Gantt, pie, timeline and more. See the [Mermaid syntax reference](https://mermaid.js.org/intro/syntax-reference.html).

> A syntax error shows a short message above the diagram and never changes your source. Diagrams follow the light or dark theme. For safety they render in strict mode: labels are plain text, with no HTML, scripts or click handlers.

## Reviewing diagram changes

In **Compare** and proposal reviews an edited diagram is one changed block with a line diff of its source; unchanged diagrams render as pictures. Search finds diagram text such as node labels and participants.

## Markdown, import and paste

A fenced block with the `mermaid` language becomes a diagram when you paste Markdown, import a `.md` file, or send Markdown through the API, CLI or MCP server. Markdown export and the API return the same fence, so diagrams round-trip with GitHub, GitLab and Obsidian.

````markdown
```mermaid
sequenceDiagram
  Author->>Reviewer: Proposal
  Reviewer-->>Author: Approved
```
````

## Export

| Format | Diagram |
| --- | --- |
| PDF, Word (.docx), Google Docs | Rendered as an image in your browser |
| Markdown | `mermaid` code fence |
| Notion | Native Mermaid code block |
| HTML, Confluence | Source as a code block labeled "Mermaid diagram" |

Shared, embedded and published pages render diagrams in the browser. Without JavaScript the source is shown instead.