Mermaid 11 15 0

mermaid 11.15.0

Overview

Mermaid generates diagrams from plain-text descriptions. Write diagram syntax inside a markdown code block fenced with ```mermaid.

All supported diagram types: flowcharts/graphs, sequence diagrams, state diagrams (v2), class diagrams, Gantt charts, entity-relationship diagrams, pie charts, git commit graphs, user journey diagrams, mindmaps, timelines, XY charts (bar/line), radar charts, quadrant charts, Sankey flow diagrams, block diagrams, cloud architecture diagrams, C4 model diagrams (context/container/component/dynamic/deployment), network packet diagrams, treemaps, Venn diagrams, Wardley strategy maps, Ishikawa fishbone diagrams, Kanban boards, and SysML requirement diagrams.

This skill provides syntax reference for every diagram type and a validation pipeline using the official Mermaid parser.

Usage

Validate a diagram

Validate mermaid code from stdin:

echo 'flowchart LR
    A-->B' | mermaid.sh validate -

Validate a markdown file (checks all ```mermaid blocks):

mermaid.sh validate ./docs/diagram.md

Validate a directory recursively:

mermaid.sh validate ./docs/ --quiet

JSON output:

mermaid.sh validate --json ./diagram.md

Convert to SVG/PNG

Use mermaid.sh render to convert .mmd or .md files to SVG or PNG:

# Single file to SVG (default output format)
mermaid.sh render -i diagram.mmd

# Explicit output path
mermaid.sh render -i diagram.mmd -o diagram.svg
mermaid.sh render -i diagram.mmd -o diagram.png

# With theme
mermaid.sh render -i diagram.mmd -t dark -o diagram.svg

# From a markdown file (extracts mermaid blocks)
mermaid.sh render -i notes.md -o output/

The script reads .mmd files (raw mermaid) or .md files (extracts fenced mermaid blocks). Output format is inferred from the -o extension (default: .svg). Run mermaid.sh render --help for all options.

Diagram types at a glance

Gotchas

• Always validate after generating — run mermaid.sh validate - with the diagram piped to stdin, or mermaid.sh validate <file> for files. Do this every time you generate a mermaid diagram, whether it's inline in a markdown block or written to .md or .mmd file. Fix any parser errors before presenting the diagram.
• The word end breaks flowcharts — if a node label contains lowercase "end", capitalize it ("End") or wrap in quotes. Same applies to sequence diagrams: use parentheses, brackets, or quotes around the word.
• Leading o or x in flowchart nodes — A---oB creates a circle edge, not a node named "oB". Add a space or capitalize: A--- Ops.
• **Every example must start with ```mermaid** — the validator extracts blocks matching this fence. Do not use ```mermaid-example or other variants in final output.
• Beta diagrams use -beta suffix — radar-beta, architecture-beta, treemap-beta, venn-beta, wardley-beta, ishikawa-beta. The keyword must include the suffix.
• stateDiagram-v2 vs stateDiagram — prefer stateDiagram-v2 (newer renderer with composite states, concurrency). The older stateDiagram still works but lacks features.
• YAML frontmatter config — diagram-level configuration goes between --- fences before the diagram keyword. Use config: for per-diagram settings and title: for display titles.
• Validation uses the real parser — run mermaid.sh validate - with diagram code piped to stdin. The script catches syntax errors the live editor would catch. Fix errors iteratively based on parser feedback.

References

Each reference file covers one diagram type with syntax rules and validated examples:

• 01-flowchart.md — Flowcharts, graphs, node shapes, edges, subgraphs, styling
• 02-sequenceDiagram.md — Participants, messages, activations, loops, alt/opt
• 03-stateDiagram.md — States, transitions, composite states, forks, concurrency
• 04-classDiagram.md — Classes, inheritance, composition, namespaces, generics
• 05-gantt.md — Tasks, sections, milestones, dependencies, date formats
• 06-erDiagram.md — Entities, relationships, cardinality, attributes, keys
• 07-pie.md — Pie charts with slices and data labels
• 08-gitGraph.md — Commits, branches, merges, cherry-picks, orientations
• 09-userJourney.md — User journeys with sections, tasks, scores
• 10-mindmap.md — Hierarchical mindmaps, shapes, icons, markdown strings
• 11-timeline.md — Timelines with sections, events, directions
• 12-xyChart.md — Bar and line charts on x/y axes
• 13-radar.md — Radar/spider charts with multiple curves
• 14-quadrantChart.md — Four-quadrant scatter plots
• 15-sankey.md — Flow/sankey diagrams showing value transfers
• 16-block.md — Block diagrams with full layout control
• 17-architecture.md — Cloud architecture with groups and services
• 18-c4.md — C4 model (context, container, component)
• 19-packet.md — Network packet structure diagrams
• 20-treemap.md — Hierarchical treemap visualizations
• 21-venn.md — Set relationships with overlapping circles
• 22-wardley.md — Wardley strategy maps
• 23-ishikawa.md — Cause-and-effect fishbone diagrams
• 24-kanban.md — Kanban workflow boards
• 25-requirementDiagram.md — SysML requirement diagrams