---
title: "Mermaid diagrams in Markdown: syntax and previews"
slug: markdown-mermaid-diagrams
excerpt: "Write a mermaid block an agent can produce, preview it before you share it, and fix the syntax slips that stop a diagram from drawing."
quickAnswer: "A Mermaid diagram in Markdown is a fenced code block whose info string is mermaid. Inside the fence you write Mermaid's own text syntax: a line that names the diagram type, such as flowchart TD or sequenceDiagram, after any optional front matter, then the nodes, arrows or messages. Neither CommonMark nor GFM includes Mermaid. To a Markdown parser the block is plain code, and drawing it is the viewer's job. A viewer that supports Mermaid can render a valid diagram; other viewers typically show the code as text. To preview, paste the code into the Mermaid Live Editor, push the file to a git host that renders Mermaid, try an editor extension, or turn it into an SVG with mermaid-cli."
keyTakeaways:
  - "Mermaid is not in CommonMark or GFM. It is a fenced code block with the info string mermaid, and the viewer decides whether to draw it."
  - "After any optional front matter, a diagram starts by naming its type, such as flowchart TD or sequenceDiagram. Unknown words and misspellings break a diagram."
  - "A lowercase end inside a flowchart node breaks it. Capitalize it, or wrap it in quotes in a sequence diagram."
  - "Put node text with parentheses inside double quotes, and write a semicolon in sequence message text as #59;."
  - "Preview options include the Mermaid Live Editor, git hosts that render Mermaid, and mermaid-cli for SVG or PNG files."
publishedDate: 2026-10-20
dateModified: 2026-10-20
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: Why does my mermaid block show up as code instead of a diagram?
    a: "A viewer without Mermaid support is one possible cause. To a CommonMark parser the block is an ordinary fenced code block, so a viewer without Mermaid typically shows the text. When Mermaid support is there, check that the info string is mermaid, that the fence closes, and that the code passes in the Mermaid Live Editor."
  - q: Do I need the mermaid info string, or will any code fence work?
    a: "You need it. The docs of hosts that draw Mermaid say to put the syntax inside a fenced code block with the mermaid language identifier. A fence with another word, or no word, normally remains a plain code block."
  - q: Can I keep a diagram in its own file instead of inside a Markdown page?
    a: "Yes. Mermaid code can live in a file with a .mmd extension. mermaid-cli takes such a file as input and writes an SVG, PNG or PDF, and some git hosts render .mmd or .mermaid files when you open them."
related:
  - markdown-code-blocks
  - rendered-vs-raw-agent-markdown
  - write-markdown-docs-your-ai-agent-can-follow
---

Agents often sketch in text. A plan file might hold a flowchart of the build steps, and a handoff note might trace who calls whom. Mermaid lets them do that in plain text, so the diagram lives right beside the prose in one file.

But that text only turns into a picture in some places.

## A mermaid block is a fenced code block

CommonMark has no diagram rule, and neither does GFM. A Mermaid diagram is a normal fenced code block. Its first fence line carries the word `mermaid` as its info string:

````markdown
```mermaid
flowchart LR
    A --> B
```
````

The spec treats everything inside a fence as literal text. It does not parse it as Markdown. Per the spec, that first word usually names a language, and each viewer decides what to do with it. So the parser hands the viewer a block of code tagged `mermaid`.

What happens next depends on the viewer. A viewer with Mermaid support can pass the text to Mermaid, which can draw a valid diagram. A viewer without it typically shows the lines as a code block, like any other fence. For fence rules in general, such as tildes and closing fences, see [Markdown code blocks](markdown-code-blocks.md).

## Mermaid syntax basics

Each diagram definition begins by declaring its type. Optional front matter can sit above that line. It is the one exception the docs name. The type line tells Mermaid's parser what kind of diagram to build. Everything after it defines the parts. Mermaid's docs warn that unknown words and misspellings break a diagram, so the type name has to be exact.

### A small flowchart

```mermaid
flowchart TD
    A[Jane Doe drafts the plan] --> B{Plan approved?}
    B -->|Yes| C[Doe Holdings starts work]
    B -->|No| D["Jane revises (round 2)"]
    D --> B
```

What each piece does:

- **`flowchart TD`** declares a flowchart drawn top to bottom. `TB` means the same thing, and `LR` runs left to right. You can write `graph` in place of `flowchart`.
- **`A[...]`** is a node with an id of `A` and whatever sits between `[` and `]` shown in a box.
- **`B{...}`** makes a rhombus, the usual shape for a decision.
- **`-->`** draws a link with an arrowhead. `-->|Yes|` puts text on that link.
- **The quotes in node `D`** let the text hold parentheses without breaking the shape syntax.

A semicolon after each statement is optional.

### A small sequence diagram

```mermaid
sequenceDiagram
    participant J as Jane Doe
    participant A as Agent
    J->>A: Write the release plan
    A-->>J: Plan saved to plan.md
    Note over J,A: Jane reviews before merge
```

- **`sequenceDiagram`** declares the type.
- **`participant J as Jane Doe`** gives a short id and a longer label. Participants appear in the order the source lists them.
- **`->>`** is a solid line with an arrowhead, and **`-->>`** is a dotted one. The message text follows the colon.
- **`Note over J,A:`** places a note across both participants. You can also write `right of` or `left of` a single participant.

In both diagram types, a line starting with `%%` is a comment. A comment needs its own line.

## Preview a diagram before you share it

Four options let you see the picture.

1. **The Mermaid Live Editor.** Paste the diagram code into mermaid.live. Mermaid's own docs call it a practice area, and one git host's docs suggest it for finding and fixing errors in Mermaid code.
2. **A git host that renders Mermaid.** Some hosts draw mermaid blocks in Markdown files, issues and pull requests. Their docs describe the same input: Mermaid syntax inside a fence marked `mermaid`. The Mermaid version can differ by host, and one documents Mermaid 11. On some hosts, a mermaid block that holds only the word `info` shows the version in use. Some hosts also render files saved with a `.mmd` or `.mermaid` extension.
3. **An editor extension.** Some editors have plugins that add Mermaid previews, and Mermaid's docs link to a list of community integrations. Support varies, so test one diagram first.
4. **mermaid-cli.** The command line tool reads a Mermaid file and writes an SVG, PNG or PDF. It installs with `npm install -g @mermaid-js/mermaid-cli`, and `mmdc -i plan.mmd -o plan.svg` makes an image. Point it at a Markdown file instead, as in `mmdc -i plan.md -o plan-out.md`, and it finds each mermaid block, writes an SVG for each one, and swaps in image links that point to them.

One host's docs warn that running a third-party Mermaid plugin there may cause errors.

## Common syntax errors agents make

The docs identify these syntax hazards. Each fix below comes from Mermaid's docs, except the last, which comes from the CommonMark spec.

1. **A lowercase `end` in a flowchart node.** Typing `end` in all lowercase breaks a flowchart. Write `End` or `END` instead. In a sequence diagram, the word can also break things; wrap it in quotes, parentheses or brackets, such as `(end)`.
2. **Parentheses or brackets in node text.** `D[Jane revises (round 2)]` confuses the shape parser. Put the text in double quotes: `D["Jane revises (round 2)"]`.
3. **A node id that starts with `o` or `x` right after a link.** `A---oB` makes a circle edge and `A---xB` makes a cross edge. Add a space or capitalize the letter, as in `dev--- ops` or `dev---Ops`.
4. **A misspelled or missing type line.** `flowhcart TD` breaks the diagram, and so does a block that opens straight into `A --> B`, because Mermaid expects the type line before the diagram code. Put a valid type line first, after any front matter.
5. **A semicolon inside sequence message text.** Semicolons can stand in for line breaks, so Mermaid's docs say to write `#59;` to include one in message text. The same entity codes work in flowchart text, such as `#quot;` for a double quote.
6. **Curly braces in a comment.** A comment like `%% {draft}` looks like a directive and confuses the renderer. Keep `{}` out of `%%` lines.
7. **A broken front matter block in the diagram.** Mermaid accepts YAML settings placed above the diagram code, fenced by a `---` line on each side. The first `---` must be alone on its line. Mermaid silently ignores a misspelled setting, but a badly formed block breaks the diagram.
8. **A fence that never closes.** This one is plain Markdown. Under CommonMark, a fenced block with no closing fence keeps going until its containing block or the document ends. Every line after it becomes part of the diagram code, so the diagram will likely fail to draw.

## Agent-written diagram tips

These habits help agent output draw on the first try.

1. **Name the type in your rules.** Add a line to the agent's rules file asking it to give each mermaid block a type line such as `flowchart TD` or `sequenceDiagram`, and to quote any node text that holds punctuation. For wording that agents obey, see [agent-ready Markdown docs](write-markdown-docs-your-ai-agent-can-follow.md).
2. **Ask for titles and descriptions.** Mermaid accepts `accTitle:` and `accDescr:` lines. When mermaid-cli turns a Markdown file into images, it uses them as the image title and alt text.
3. **Keep a text summary next to the diagram.** Readers whose viewer shows only code still get the point from one plain sentence.
4. **Check both views.** A diagram can draw in one place and show as code in another. Read [when to render and when to read raw](rendered-vs-raw-agent-markdown.md) for the trade-off. The [review guide](how-to-review-markdown-your-ai-agents-write.md) fits diagrams into a full pass. Our [syntax guide](markdown-syntax-guide.md) walks through the core elements that surround them.

## Where Sashmark fits

Work continues on Sashmark, a planned desktop reader and editor for the Markdown files agents leave behind. It is in development and has not been released. The app itself has no AI features. How far along each part is shows on the [roadmap](/roadmap), with more detail in the [planned features](/features) list and the [help pages](/help).

Project news lives at [sashmark.com](https://www.sashmark.com/).