gabrielmoreira Mermaid Mode Fragility
Category: Documentation Time Saved: 30-60 minutes debugging silent render failures Battle-tested: Yes — multiple diagram types failed in production
The Problem
You write a Mermaid diagram in your docs. The syntax is valid. The diagram renders locally. You push it live and... blank space. Or worse, corrupted output. No error message.
Why It Happens
Several Mermaid diagram modes have undocumented constraints around colons (:) and other characters. They fail silently or produce garbage output.
The Fragile Modes
1. Timeline Mode
Uses : as time/event separator. Breaks on HH:MM times.
timeline
title Project Timeline
2024-01 : Project kickoff
2024-02 : Design complete
10:30 : Daily standup ← BREAKS: colon in time value
2. GitGraph Mode
Long linear chains with colon-bearing quoted tags fail to render.
gitGraph
commit id: "feat: initial"
commit id: "feat: add login"
commit id: "fix: security"
... 10+ more commits ... ← BREAKS: long chains with colons
commit id: "chore: release"
3. Gantt Mode
dateFormat HH:mm mis-parses task lines with times.
gantt
dateFormat HH:mm
title Daily Schedule
Meeting : 09:00, 1h ← BREAKS: colon in description
Standup : 10:30, 30m
The Rule
Default to flowchart for any diagram with arbitrary text labels.
Flowchart (TB/LR/TD) is the only Mermaid mode that reliably survives complex content:
flowchart TB
A[09:00 Meeting] --> B[10:30 Standup]
B --> C[14:00 Review]
Safe vs Fragile Modes
| Mode | Status | Constraint |
|---|---|---|
flowchart |
✅ Safe | None — handles any content |
sequenceDiagram |
✅ Safe | Standard message format |
classDiagram |
✅ Safe | Standard notation |
stateDiagram |
⚠️ Caution | Colons in state names |
erDiagram |
✅ Safe | Standard notation |
timeline |
❌ Fragile | No colons in events |
gitGraph |
❌ Fragile | Short chains only |
gantt |
❌ Fragile | No HH:MM in dateFormat |
journey |
⚠️ Caution | Score format sensitive |
Flowchart Alternatives
Instead of Timeline
flowchart LR
A[Jan: Kickoff] --> B[Feb: Design] --> C[Mar: Build]
Instead of GitGraph
flowchart TB
A[main] --> B[feat/login]
B --> C[feat/auth]
C --> D[release/1.0]
Instead of Gantt
flowchart TB
subgraph Morning
A[09:00 Meeting]
B[10:30 Standup]
end
subgraph Afternoon
C[14:00 Review]
D[16:00 Deploy]
end
Debugging Silent Failures
- Check browser console — Mermaid sometimes logs parse errors
- Simplify content — Remove colons, special chars
- Test incrementally — Add nodes one at a time
- Try flowchart — If it works in flowchart, the mode is the problem
Verification Checklist
- Does diagram contain colons in text?
- Using a fragile mode (timeline, gitGraph, gantt)?
- Test in Mermaid Live Editor before committing
- Consider flowchart for complex text content
Related Skills
docs-decay-velocity— Documentation maintenance