mermaid-mode-fragility

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