mermaid-diagrams

Mermaid Diagramming

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

Core Syntax Structure

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
Use %% for comments
Line breaks and indentation improve readability but aren't required
Unknown words break diagrams; parameters fail silently

Diagram Type Selection Guide

Choose the right diagram type:

Flowcharts - Processes, algorithms, decision trees, user journeys
- Business processes and workflows
- Algorithm logic and control flow
- Deployment pipelines
- Decision trees
Sequence Diagrams - Temporal interactions, message flows
- API request/response flows
- User authentication flows
- System component interactions
- Method call sequences
Class Diagrams - Domain modeling, OOP design, entity relationships
- Domain-driven design documentation
- Object-oriented class structures
- Entity relationships and dependencies
Entity Relationship Diagrams (ERD) - Database schemas
- Table relationships
- Data modeling
- Schema design
C4 Diagrams - Software architecture at multiple levels
- System Context (systems and users)
- Container (applications, databases, services)
- Component (internal structure)
- Code (class/interface level)
State Diagrams - State machines, lifecycle states
- UI component states
- Workflow status transitions
- Object lifecycles
Git Graphs - Version control branching strategies
- Feature branching workflows
- Release management
- Merge strategies
Gantt Charts - Project timelines, scheduling
- Project planning and milestones
- Resource allocation
- Dependency tracking
Pie Charts - Simple data proportions
- Market share visualization
- Budget allocation
- Survey results
Quadrant Charts - Two-dimensional data plotting
- Priority matrices
- Risk/impact assessment
- Feature prioritization
XY Charts - Bar and line charts with axes
- Sales trends over time
- Performance metrics
- Comparative data analysis
Radar Charts - Multi-dimensional comparison
- Skills assessment
- Product feature comparison
- Performance evaluation
Sankey Diagrams - Flow visualization
- Energy/material flows
- Budget flows
- User journey funnels
Mindmaps - Information hierarchy and brainstorming
- Concept mapping
- Idea organization
- Knowledge structures
Timelines - Chronological events
- Project history
- Product roadmaps
- Historical events
Kanban Boards - Task workflow visualization
- Sprint planning
- Bug tracking workflows
- Status tracking
Block Diagrams - System component visualization
- Hardware systems
- Software modules
- Control systems
Packet Diagrams - Network packet structures
- Protocol documentation
- Network packet analysis
- Binary data layouts
Requirement Diagrams - Requirements traceability
- System requirements
- Compliance tracking
- Verification methods
Treemaps - Hierarchical data proportions
- Disk usage
- Budget breakdowns
- Portfolio allocation
Venn Diagrams - Set relationships
- Feature overlap analysis
- Audience segmentation
- Capability comparison
Ishikawa (Fishbone) Diagrams - Cause-and-effect analysis
- Root cause analysis
- Quality improvement
- Problem diagnosis
Wardley Maps - Strategy and evolution
- Business strategy
- Value chain mapping
- Component evolution
TreeViews - Directory and hierarchy display
- Folder structures
- Org charts
- File system navigation
Event Modeling - Event-driven system design
- Event-sourced systems
- Domain event flows
- System state transitions
ZenUML - Alternative sequence diagram syntax
- Code-like sequence descriptions
- Lightweight interaction diagrams
Architecture Diagrams - Cloud and infrastructure
- Cloud service relationships
- CI/CD pipelines
- System topology
User Journey Diagrams - User experience flows
- Task completion analysis
- Satisfaction scoring
- UX touchpoints

Quick Start Examples

Class Diagram (Domain Model)

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram (API Flow)

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart (User Journey)

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (Database Schema)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

State Diagram (Lifecycle)

stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Approved : approve
    Review --> Rejected : reject
    Rejected --> Draft : revise
    Approved --> Published : publish
    Published --> [*]

Gantt Chart (Project Timeline)

gantt
    title Project Schedule
    dateFormat  YYYY-MM-DD
    section Design
    Requirements    :a1, 2024-01-01, 10d
    UI/UX Design    :after a1, 15d
    section Development
    Backend API     :2024-01-20, 20d
    Frontend        :2024-02-01, 25d
    section Testing
    Integration     :2024-02-20, 10d
    UAT             :2024-03-01, 10d

Mindmap (Information Hierarchy)

mindmap
  root((Project Management))
    Planning
      Requirements
      Architecture
      Timeline
    Execution
      Development
      Testing
      Deployment
    Monitoring
      Metrics
      Alerts
      Improvements

Kanban Board (Workflow)

kanban
    Todo
        [Write documentation]
        [Fix bug #123]
    In Progress
        docs[Review PR #456]
    Done
        [Setup CI/CD]
        [Deploy to staging]

Detailed References

For in-depth guidance on specific diagram types, see:

references/class-diagrams.md - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
references/c4-diagrams.md - System context, container, component diagrams, boundaries
references/architecture-diagrams.md - Cloud services, infrastructure, CI/CD deployments
references/state-diagrams.md - States, transitions, composite states, forks/joins
references/gantt-charts.md - Tasks, milestones, dependencies, sections
references/mindmaps.md - Hierarchical nodes, different node shapes
references/git-graphs.md - Branches, commits, merges, tags
references/pie-charts.md - Data slices, labels, percentages
references/quadrant-charts.md - Axes, data points, quadrant labels
references/xy-charts.md - Bar charts, line charts, axes configuration
references/radar-charts.md - Axes, curves, data comparison
references/sankey-diagrams.md - Nodes, flows, values
references/timelines.md - Events, dates, sections
references/kanban-diagrams.md - Columns, tasks, metadata
references/block-diagrams.md - Blocks, connections, layouts
references/packet-diagrams.md - Bit fields, headers, data
references/requirement-diagrams.md - Requirements, elements, relationships
references/treemaps.md - Hierarchical rectangles, values
references/venn-diagrams.md - Sets, unions, intersections
references/ishikawa-diagrams.md - Causes, effects, categories
references/wardley-maps.md - Value chains, evolution, components
references/treeviews.md - Directory structures, hierarchies
references/event-modeling.md - Events, commands, swimlanes
references/zenuml-diagrams.md - Alternative sequence syntax
references/user-journeys.md - Tasks, sections, scoring
references/advanced-features.md - Themes, styling, configuration, layout options

Best Practices

Start Simple - Begin with core entities/components, add details incrementally
Use Meaningful Names - Clear labels make diagrams self-documenting
Comment Extensively - Use %% comments to explain complex relationships
Keep Focused - One diagram per concept; split large diagrams into multiple focused views
Version Control - Store .mmd files alongside code for easy updates
Add Context - Include titles and notes to explain diagram purpose
Iterate - Refine diagrams as understanding evolves

Configuration and Theming

Configure diagrams using frontmatter:

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Available themes: default, forest, dark, neutral, base

Layout options:

layout: dagre (default) - Classic balanced layout
layout: elk - Advanced layout for complex diagrams (requires integration)

Look options:

look: classic - Traditional Mermaid style
look: handDrawn - Sketch-like appearance

Exporting and Rendering

Native support in:

GitHub/GitLab - Automatically renders in Markdown
VS Code - With Markdown Mermaid extension
Notion, Obsidian, Confluence - Built-in support

Export options:

Mermaid Live Editor - Online editor with PNG/SVG export
Mermaid CLI - npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
Docker - docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

Breaking characters - Avoid {} in comments, use proper escape sequences for special characters
Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
Overcomplexity - Split complex diagrams into multiple focused views
Missing relationships - Document all important connections between entities

When to Create Diagrams

Always diagram when:

Starting new projects or features
Documenting complex systems
Explaining architecture decisions
Designing database schemas
Planning refactoring efforts
Onboarding new team members

Use diagrams to:

Align stakeholders on technical decisions
Document domain models collaboratively
Visualize data flows and system interactions
Plan before coding
Create living documentation that evolves with code