Mermaid Diagrams

Overview

Add interactive diagrams in your documentation using Mermaid syntax. The component automatically adapts to light and dark themes, provides zoom controls, and supports fullscreen viewing for better diagram exploration.

Common use cases:

• Flowcharts for processes and workflows
• Sequence diagrams for API interactions
• System architecture diagrams
• State diagrams for application flows
• Entity relationship diagrams for database schemas
• Gantt charts for project timelines

Basic syntax

Use Mermaid code blocks with triple backticks and the mermaid language identifier:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Interactive features

Zoom controls

Hover over any diagram to reveal zoom controls in the top-right corner:

• Zoom In - Magnify the diagram up to 300%
• Zoom Out - Reduce the diagram down to 50%
• Reset - Click the percentage to reset to 100%
• Fullscreen - View the diagram in fullscreen mode

Diagram types

Flowcharts

Visualize processes, workflows, and decision trees:

```mermaid
graph TD
    A[User Request] --> B{Authenticated?}
    B -->|Yes| C[Process Request]
    B -->|No| D[Redirect to Login]
    C --> E[Return Response]
    D --> F[Show Login Page]
```

Sequence diagrams

Document API calls, interactions, and message flows:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database
    
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: Success
    API-->>Client: 201 Created
```

Class diagrams

Show object-oriented structures and relationships:

```mermaid
classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    class Admin {
        +String permissions
        +manageUsers()
    }
    User <|-- Admin
```

State diagrams

Illustrate application states and transitions:

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Success: Complete
    Processing --> Error: Fail
    Success --> [*]
    Error --> Idle: Retry
```

Entity relationship diagrams

Design database schemas and relationships:

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    USER {
        string id PK
        string name
        string email
    }
    ORDER {
        string id PK
        string user_id FK
        date created_at
    }
```

Gantt charts

Plan project timelines and milestones:

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design           :2024-01-01, 30d
    Development      :2024-01-15, 45d
    section Phase 2
    Testing          :2024-02-15, 20d
    Deployment       :2024-03-07, 10d
```

Git graphs

Visualize branching strategies and workflows:

```mermaid
gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout develop
    merge feature
    checkout main
    merge develop
```

Graph directions

Control flowchart layout orientation:

```mermaid
graph LR
    A[Input] --> B[Process] --> C[Output]
```

Node shapes

Customize node appearance in flowcharts:

```mermaid
graph TD
    A[Rectangle]
    B(Rounded Rectangle)
    C([Stadium Shape])
    D[[Subroutine]]
    E[(Database)]
    F((Circle))
    G>Asymmetric]
    H{Diamond}
    I{{Hexagon}}
```

Arrow types

Define different connection styles:

```mermaid
graph LR
    A --> B
    C --- D
    E -.-> F
    G ==> H
    I -- Text --> J
```

Theme support

Diagrams automatically match your documentation theme:

• Light mode - Uses default Mermaid theme with light backgrounds
• Dark mode - Uses dark Mermaid theme with appropriate colors
• Automatic switching - Updates when theme changes

Syntax

Common patterns

• API documentation - Sequence diagrams showing request/response flows
• Architecture diagrams - Flowcharts illustrating system components
• State machines - State diagrams for complex application logic
• Database design - ER diagrams showing table relationships
• Project planning - Gantt charts with milestones and deadlines
• Git workflows - Branch strategies and merge patterns
• Process documentation - Flowcharts with decision points
• Tutorial flows - Step-by-step visual guides

Best practices

Diagram complexity:

• Keep diagrams focused on a single concept
• Break complex systems into multiple diagrams
• Use subgraphs for logical grouping
• Limit nodes to 10-15 for readability

Labeling:

• Use clear, concise node labels
• Add descriptive text to connections
• Include legends for complex diagrams
• Maintain consistent terminology

Layout:

• Choose appropriate direction (TD, LR, etc.)
• Use proper node shapes for context
• Space nodes evenly for clarity
• Test in both light and dark themes

Accessibility:

• Provide text descriptions for complex diagrams
• Use sufficient color contrast
• Include alternative text explanations
• Test zoom functionality for details

Mermaid resources

• Official Documentation - mermaid.js.org
• Live Editor - mermaid.live for testing syntax
• Syntax Reference - Complete guide to all diagram types
• Examples Gallery - Collection of diagram templates