How do you embed a Mermaid diagram in Markdown?

Write the diagram inside a fenced code block tagged `mermaid`. Open with three backticks and the word mermaid, write the diagram in Mermaid's text syntax (for example `graph TD; A-->B`), then close with three backticks. Any renderer with Mermaid support turns that block into an SVG diagram. Plain, GitHub, Obsidian, and many doc tools render these blocks automatically.

Mermaid is a tool that renders diagrams from a simple text syntax. Instead of dragging boxes in a drawing app, you describe the diagram in words (nodes, arrows, labels) and Mermaid draws it. Because the source is text, it lives inside your Markdown, diffs cleanly in Git, and can be generated or edited by AI. It supports flowcharts, sequence diagrams, Gantt charts, ER diagrams, and more.

What diagram types does Mermaid support?

The common ones: flowcharts (graph / flowchart) for processes and decisions, sequence diagrams for interactions over time, class and ER diagrams for data models, state diagrams for state machines, Gantt charts for timelines, and pie charts. Flowcharts and sequence diagrams cover most everyday documentation needs.

Why use Mermaid instead of pasting an image of a diagram?

A pasted image is dead: you cannot edit it without the original tool, it does not diff in Git, it breaks when the doc moves, and AI cannot read or update it. A Mermaid block is live text: anyone can edit the diagram by changing a line, it versions cleanly with the rest of the doc, and an AI can generate or revise it. The diagram stays part of the document, not an attachment to it.

Can AI generate Mermaid diagrams?

Yes, and this is one of Mermaid's biggest advantages. Because the diagram is text, an AI can write it from a description: 'draw a flowchart of the signup flow' produces a valid Mermaid block you drop into your doc. You can also ask AI to update an existing diagram by editing the text, which is impossible with a flattened image.

Does Plain support Mermaid diagrams in documents?

Yes. Plain renders fenced `mermaid` blocks inside docs as live diagrams, so a flowchart or sequence diagram sits inline with your prose rather than as a pasted picture. Since a Plain doc is a web page shared as a link, the diagram stays interactive and current, and because the source is Markdown you (or the AI) can edit the diagram by editing its text.

2026-06-206 min·#how-to#doc

How to embed Mermaid diagrams in a document

Zephyr WhimsyEditorial · 2026-06-20

Mermaid lets you write diagrams as text, right inside your Markdown. Here's the syntax, the common diagram types, and how to keep the diagram a living part of the doc instead of a pasted image.

Most documents that need a diagram end up with a screenshot pasted in: a flowchart someone drew in a separate app, exported as a PNG, and dropped into the doc. It looks fine until you need to change it, and then it is a dead end. Mermaid fixes this by letting you write the diagram as text, right inside your Markdown, so it stays a living part of the document.

Here is the syntax, the diagram types worth knowing, and why keeping the diagram as text matters more than it sounds.

The basic syntax

A Mermaid diagram goes inside a fenced code block tagged mermaid. You write the diagram in Mermaid's text syntax, and a renderer with Mermaid support draws it:

```mermaid
graph TD
  A[User signs up] --> B{Email verified?}
  B -->|Yes| C[Create account]
  B -->|No| D[Send reminder]
```

That block renders as a flowchart: a box, a decision diamond, and two branches. The whole thing is four lines of text. To change the flow, you edit a line, not a picture.

The diagram types you will actually use

Mermaid supports many types, but two cover most documentation:

Flowcharts (graph / flowchart) for processes, decisions, and architecture. TD means top-down; LR means left-to-right. Nodes in [brackets] are boxes, {braces} are decision diamonds, and --> draws an arrow.

Sequence diagrams for interactions over time, like an API call or a handoff between services:

```mermaid
sequenceDiagram
  Client->>API: POST /login
  API->>DB: check credentials
  DB-->>API: ok
  API-->>Client: token
```

Beyond those, Mermaid does state diagrams, ER diagrams for data models, Gantt charts for timelines, and pie charts. But if you learn only flowcharts and sequence diagrams, you can document most systems.

Where Mermaid blocks render

The same mermaid block renders in a lot of places: GitHub and GitLab Markdown, Obsidian, many static site generators, and web-first doc tools. Anywhere with Mermaid support turns the text into an SVG. If a tool does not support it, you see the raw text, which is still readable, just not drawn. That graceful fallback is part of why text-based diagrams are safe to use.

Why text beats a pasted image

This is the part that matters more than the syntax. A pasted diagram image is dead in four specific ways:

Pasted image                  Mermaid block
------------------------------------------------------
edit needs the original tool  edit one line of text
does not diff in Git          diffs cleanly with the doc
breaks if the file moves      travels with the Markdown
AI can't read or update it    AI can generate and revise it

That last row is the quiet revolution. Because a Mermaid diagram is text, an AI can write one from a sentence: ask for "a flowchart of the onboarding flow" and get a valid block you drop in. You can also ask it to update an existing diagram by editing the text, something you simply cannot do with a flattened PNG. The diagram becomes a first-class, editable part of the doc instead of an attachment that rots.

Keeping the diagram a living part of the doc

The point of all this is that the diagram should stay inside the document and stay editable. This is the same principle behind keeping the whole document as diffable text rather than a binary file: when the source is text, everything in it, prose and diagrams alike, can be versioned, reviewed, and edited by both humans and AI.

This is how Plain handles it. A Plain doc is Markdown rendered as a web page, and a fenced mermaid block renders inline as a live diagram next to your prose. Because the doc is a web page shared as a link, the diagram stays current for everyone who opens it, and because the source is Markdown, you or the AI can revise the diagram by editing its text. The diagram is part of the document you ship, not a picture you remembered to paste. For the broader case on why a doc should be a link, not a file, that piece goes deeper.

The short version

To embed a Mermaid diagram: write it in a fenced mermaid code block using Mermaid's text syntax, and any renderer with Mermaid support draws it inline. Learn flowcharts and sequence diagrams first; they cover most needs. And keep the diagram as text rather than a pasted image, because text diffs, travels with the doc, and can be generated and edited by AI. The diagram stops being a dead picture and becomes a living part of the document.

Todos los posts Abrir el espacio de trabajo