Mermaid Diagrams

Mermaid Diagrams

Create visual diagrams directly in Markdown files using Mermaid syntax. Diagrams render automatically on GitHub, in VS Code, and many other Markdown viewers.

When to Use This Skill

• User asks to "add a diagram", "create a chart", "visualize", or "show graphically"
• Documentation needs visual representation of workflows, processes, or architecture
• Feature files or ADRs would benefit from visual diagrams
• Explaining complex logic flows, state machines, or relationships
• Creating documentation for system architecture or data models
• Visualizing timelines, schedules, or project plans

Supported Diagram Types

Creating Mermaid Diagrams

Basic Syntax

Wrap Mermaid code in fenced code blocks with mermaid language identifier:

```mermaid
<diagram-type>
  <diagram-content>
```

Flowchart Example

```mermaid
flowchart TD
    Start([Start]) --> Input[Get User Input]
    Input --> Validate{Valid?}
    Validate -->|Yes| Process[Process Data]
    Validate -->|No| Error[Show Error]
    Process --> Save[(Save to DB)]
    Save --> End([End])
    Error --> Input
```

Sequence Diagram Example

```mermaid
sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /create
    API->>Database: INSERT query
    Database-->>API: Success
    API-->>User: 201 Created
```

Class Diagram Example

```mermaid
classDiagram
    class Module {
        +String name
        +String version
        +deploy()
        +validate()
    }
    class Resource {
        +String id
        +Map tags
    }
    Module --> Resource : creates
```

State Diagram Example

```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Running : start
    Running --> Completed : success
    Running --> Failed : error
    Failed --> Pending : retry
    Completed --> [*]
```

Entity Relationship Diagram Example

```mermaid
erDiagram
    MODULE ||--o{ RESOURCE : creates
    MODULE {
        string name
        string version
        string provider
    }
    RESOURCE {
        string id
        string type
        map tags
    }
```

Gantt Chart Example

```mermaid
gantt
    title Implementation Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Design           :2026-01-01, 7d
    Implementation   :2026-01-08, 14d
    section Phase 2
    Testing          :2026-01-22, 7d
    Deployment       :2026-01-29, 3d
```

Best Practices

1. Choose the Right Diagram Type

2. Keep Diagrams Simple

• Limit nodes: 10-15 nodes per diagram (split complex flows)
• Use clear labels: Short, descriptive text
• Avoid clutter: One main concept per diagram
• Use subgraphs: Group related elements

3. Use Consistent Styling

```mermaid
flowchart LR
    style Start fill:#90EE90
    style End fill:#FFB6C1
    style Error fill:#FFA07A

    Start --> Process
    Process --> End
    Process --> Error
```

4. Add Descriptive Context

Always add explanatory text before and/or after diagrams:

## Deployment Workflow

The following diagram shows the complete deployment process from code commit to production:

```mermaid
flowchart TD
    Commit --> CI
    CI --> Test
    Test --> Deploy
```

After deployment, the system automatically runs health checks and monitoring.

Common Patterns

Agent Handoff Workflow

```mermaid
flowchart LR
    Plan[Implementation Plan] --> Shaper[Scenario Shaper]
    Shaper --> Tester[Terraform Tester]
    Tester --> Module[Module Specialist]
    Module --> Docs[Documentation]
    Docs --> Examples[Examples]

    Module -.feedback.-> Tester
    Module -.feedback.-> Shaper
    Docs -.feedback.-> Module
    Examples -.feedback.-> Module
```

TDD Workflow

```mermaid
stateDiagram-v2
    [*] --> WriteScenario
    WriteScenario --> WriteTest
    WriteTest --> RunTest
    RunTest --> TestFails
    TestFails --> Implement
    Implement --> RunTest
    RunTest --> TestPasses
    TestPasses --> Refactor
    Refactor --> [*]
```

Module Architecture

```mermaid
graph TB
    subgraph "Module Root"
        Main[main.tf]
        Vars[variables.tf]
        Outputs[outputs.tf]
    end

    subgraph "Examples"
        Basic[examples/basic/]
        Complete[examples/complete/]
    end

    subgraph "Tests"
        Unit[tests/unit.tftest.hcl]
        Integration[tests/integration.tftest.hcl]
    end

    Main --> Examples
    Tests -.validates.-> Main
```

Troubleshooting

Advanced Features

Clickable Nodes

```mermaid
flowchart LR
    A[Documentation] --> B[Examples]
    click A "https://github.com/repo/docs" "View Docs"
    click B "https://github.com/repo/examples" "View Examples"
```

Styling and Themes

```mermaid
%%{init: {'theme':'forest'}}%%
flowchart TD
    A --> B
```

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

Subgraphs for Organization

```mermaid
flowchart TB
    subgraph "Frontend"
        UI[User Interface]
        API[API Client]
    end

    subgraph "Backend"
        Server[API Server]
        DB[(Database)]
    end

    UI --> API
    API --> Server
    Server --> DB
```

References

• Mermaid Syntax Reference: https://mermaid.js.org/intro/syntax-reference.html
• GitHub Diagrams Documentation: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
• Mermaid Live Editor: https://mermaid.live/ (for testing/validation)
• Flowchart Syntax: https://mermaid.js.org/syntax/flowchart.html
• Sequence Diagram Syntax: https://mermaid.js.org/syntax/sequenceDiagram.html
• Class Diagram Syntax: https://mermaid.js.org/syntax/classDiagram.html
• State Diagram Syntax: https://mermaid.js.org/syntax/stateDiagram.html
• ER Diagram Syntax: https://mermaid.js.org/syntax/entityRelationshipDiagram.html
• Gantt Chart Syntax: https://mermaid.js.org/syntax/gantt.html

Quick Start Checklist

• Identify what needs visualization
• Choose appropriate diagram type
• Draft diagram structure (nodes, connections, flow)
• Add Mermaid code block to Markdown file
• Validate syntax at mermaid.live
• Add explanatory text around diagram
• Test rendering on GitHub/VS Code
• Refine styling and layout if needed

Converted and distributed by TomeVault — claim your Tome and manage your conversions.