Mermaid Mode Fragility

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

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

1. Check browser console — Mermaid sometimes logs parse errors
2. Simplify content — Remove colons and special chars
3. Test incrementally — Add nodes one at a time
4. 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

• markdown-mermaid — full markdown + Mermaid style guide
• lint-clean-markdown — pass markdownlint on first attempt