| type | skill |
| lifecycle | stable |
| name | mermaid-mode-fragility |
| description | Mermaid renders blank or garbled — diagnose silent failures in timeline, gitGraph, gantt; default to flowchart for arbitrary text |
| tier | standard |
| inheritance | inheritable |
| applyTo | **/*.md,**/*mermaid*,**/*diagram* |
| currency | 2026-04-30T00:00:00.000Z |
| lastReviewed | 2026-04-30T00:00:00.000Z |
Mermaid Mode Fragility
Battle-tested in production — multiple Mermaid modes fail silently on colons and quoted tags. Default to flowchart for any diagram with arbitrary text content.
When to Use
- A Mermaid diagram renders blank or garbled with no error message
- You're about to use
timeline, gitGraph, or gantt with arbitrary text
- The diagram works in Mermaid Live Editor but breaks on GitHub
- Time values like
HH:MM appear in any diagram label
Why It Happens
Several Mermaid modes have undocumented constraints around colons (:) and other characters. They fail silently or produce garbage output. The renderer does not surface the parse error to the page.
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 |
