mermaid

name	mermaid
description	Pitfalls to avoid when writing Mermaid diagrams. Use whenever generating a `mermaid` code block, a `<pre class="mermaid">` block, or troubleshooting a Mermaid render error. Assumes you already know Mermaid syntax — this skill only covers the gotchas that silently break renders.

mermaid

You already know Mermaid syntax. These are the things that break it.

Pitfalls

• Single spaces only. Never align tokens with multiple spaces. A -->|no| B fails. A -->|no| B works. The parser treats extra whitespace as a token.
• Reserved words as node IDs. Avoid end, subgraph, direction, class, classDef, style, click, linkStyle — case-insensitively in flowcharts. End, END, and end all collide with the subgraph … end keyword.
• Punctuation in labels needs quotes. A[foo: bar?] fails. A["foo: bar?"] works. Quote any label with :, ?, (, ), ,, -, or unicode.
• Edge-label syntax. Prefer A -- text --> B when the label is anything beyond a single word — it tokenises more reliably than A -->|text| B.
• Indentation is fine (2 spaces is conventional), but mixing tabs and spaces inside one diagram breaks the parser. Pick one.
• graph vs flowchart are aliases for the same diagram. Pick one and stick to it within a diagram.
• Newlines matter. Don't put two statements on one line without ; between them: A --> B; B --> C works, A --> B B --> C doesn't.

When rendering inside HTML

• Use <pre class="mermaid">…</pre>. Do not wrap the <pre> in <code> — that prevents Mermaid from finding it.
• Don't HTML-entity-encode the diagram body. --> will render as text, not parse as an arrow. Write --> directly inside <pre>.
• Under file:// origins, Mermaid v10+ fails because it lazy-loads diagram modules via dynamic import. Serve over http:// (see rich-response skill).

Debugging

When a render fails, the console error includes a line number and a caret (^) pointing at the offending position. The line number references the diagram source (not the HTML file). Read the caret position, not the expected-token list — the expected list is usually misleading.

Diagram-type cheat (for reference)

Type	First line
Flowchart	flowchart TD / LR
Sequence	sequenceDiagram
Class	classDiagram
State	stateDiagram-v2
ER	erDiagram
Gantt	gantt
Pie	pie title …
Mindmap	mindmap
Timeline	timeline
Quadrant	quadrantChart
User journey	journey
Git graph	gitGraph