Markdown viewer that draws Mermaid diagrams in place

The diagram belongs to the document

There is no shortage of Mermaid editors, and the best of them solve one problem well: drawing a diagram on its own. What almost none of them solve is the real documentation case, where the diagram is one paragraph among others — it comes after an explanation, before a table of rules, inside a section that has a title and context.

Here the whole file is read. mermaid blocks are drawn where they are, and the rest of the Markdown carries on being Markdown. It is the same rendering GitHub does in a README, available before you commit.

That difference shows up most in review. A reviewer looking at an architecture change needs the diagram and the paragraph that explains it on the same screen. Copying the diagram into a separate tool to look at it is how a stale drawing survives three releases.

How to write the block

A fenced code block with mermaid as the language, and the diagram inside it:

```mermaid
flowchart LR
  A[Commit] --> B{Tests green?}
  B -- yes --> C[Build image]
  B -- no --> X[Block and notify]
```

The first line inside the fence declares the diagram type. Everything after it is that type's own syntax, which is why an error in a flowchart reads nothing like an error in a sequence diagram. If the syntax is wrong the block stays visible as text instead of vanishing — that is what lets you find the line to fix.

What you can draw

A practical rule: one diagram per section, and if a diagram needs a legend it is probably two diagrams. Mermaid makes it cheap to add nodes, which makes it easy to end up with a drawing nobody reads.

Why keep the diagram as text

A diagram exported as an image goes stale quietly. The picture stays in the repository long after the flow changed, and nobody notices, because a .png does not show up readably in a pull request. In Mermaid the diagram is code — the change appears line by line in the diff, it goes through review like any other change, and it does not need the original drawing tool to be edited.

It also survives the person who made it. A diagram in a proprietary format is only editable by whoever has that tool installed; six fenced lines in a Markdown file are editable by anyone who can open the file.

Where Mermaid actually renders

Which is the argument for checking the drawing before you push it: the places that render Mermaid are the places where the diagram carries the explanation, and a diagram with a syntax error there shows up as an error box in front of everyone.

The four mistakes that break a diagram

A space in a node id. A B[Label] is two tokens, not one node. Ids have to be a single word; the readable text goes in the brackets, and if it contains punctuation it goes in double quotes: A["Build, then sign"].

The diagram type missing from the first line. Without flowchart, sequenceDiagram or another keyword opening the block, Mermaid has no grammar to parse against and refuses the whole thing. A block that renders nowhere usually starts one line too late.

Reserved characters in a label. Curly braces, square brackets and the pipe character mean something to the parser. In a label they need quoting, which is the most common reason a diagram that worked yesterday stops working after an innocuous text edit.

Case-sensitive ids treated as the same node. A and a are two different nodes. A flowchart with a stray lowercase reference silently grows an extra box instead of failing, which is harder to spot than an error.

All four show up immediately in a side-by-side preview, and that is the practical argument for checking a diagram here rather than after the push: in a pull request the same mistake renders as an error box in front of every reviewer.

Frequently asked questions