Mermaid

Mermaid Diagram Renderer

Validate Mermaid syntax, then generate interactive HTML diagrams and open them in the browser. Rendering always validates first and exits without creating HTML when the syntax is invalid.

Quick Start

Pipe mermaid code to the render script:

echo 'flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[OK]
  B -->|No| D[Cancel]' | bun $SKILL_DIR/scripts/render.ts

Options

| Flag | Description | | ---------------- | ----------------------------------------------------- | | --theme | Mermaid theme: default, dark, forest, neutral | | --no-open | Write HTML file without opening in browser |

The renderer validates Mermaid syntax before writing or opening the HTML file. Invalid input produces a JSON validation report and a nonzero exit code.

Examples

# Dark theme
echo '...' | bun $SKILL_DIR/scripts/render.ts --theme dark

# Write file only (no browser)
echo '...' | bun $SKILL_DIR/scripts/render.ts --no-open

Validate Mermaid Syntax

Use [scripts/validate.ts](scripts/validate.ts) when syntax validation is needed without rendering. It accepts explicit Mermaid or Markdown file paths, or reads Mermaid or Markdown from stdin when no paths are supplied.

# Validate Mermaid source from stdin
echo 'flowchart TD
  A --> B' | bun $SKILL_DIR/scripts/validate.ts

# Validate Mermaid fences in Markdown
bun $SKILL_DIR/scripts/validate.ts README.md docs/architecture.md

# Validate a Mermaid file
bun $SKILL_DIR/scripts/validate.ts diagram.mmd

The validator writes JSON containing overall validity, detected input files, source types, diagrams, source line ranges, detected diagram types, and normalized errors with line and column locations. It exits 0 when every detected diagram is valid and 1 for syntax or input errors. Markdown files without Mermaid fences are valid and report no diagrams.

Critical Syntax Rules

NEVER use literal newlines inside node labels. Mermaid's parser is line-based — a node definition must be on a single line. Use `` for line breaks within labels.

%% ❌ WRONG — causes "Syntax error in text"
SWR1["Fresh
30 min"]

%% ✅ CORRECT
SWR1["Fresh30 min"]

Mermaid Syntax Quick Reference

Flowchart

flowchart TD
  A[Rectangle] --> B(Rounded)
  B --> C{Diamond}
  C -->|One| D[Result 1]
  C -->|Two| E[Result 2]

Direction: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)

Sequence Diagram

sequenceDiagram
  participant A as Alice
  participant B as Bob
  A->>B: Hello
  B-->>A: Hi back
  A->>B: Request
  Note over A,B: Shared note

Class Diagram

classDiagram
  class Animal {
    +String name
    +makeSound() void
  }
  Animal  Idle
  Idle --> Processing : start
  Processing --> Done : finish
  Done --> [*]

Entity Relationship

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  PRODUCT ||--o{ LINE-ITEM : "is in"

Gantt Chart

gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Phase 1
    Task A :a1, 2024-01-01, 30d
    Task B :after a1, 20d

Pie Chart

pie title Distribution
  "A" : 40
  "B" : 35
  "C" : 25

Git Graph

gitGraph
  commit
  branch feature
  checkout feature
  commit
  commit
  checkout main
  merge feature

Mindmap

mindmap
  root((Central))
    Topic A
      Subtopic 1
      Subtopic 2
    Topic B
      Subtopic 3

Timeline

timeline
  title History
  2020 : Event A
  2021 : Event B
       : Event C
  2022 : Event D

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wyattjoh
• Source: wyattjoh/skills
• License: MIT

Install and usage instructions live in the source repository linked above.