Mermaid Diagram Expert

Comprehensive Mermaid.js solution for visualization and documentation

Version: 5.0.0
Focus: Flowcharts, Sequence, Class, ER, Gantt, C4, Architecture
Tools: Mermaid CLI, Python Converter

Quick Start

Installation

# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Convert diagram
mmdc -i diagram.mmd -o output.png

Python Converter (Custom)

# scripts/mermaid-to-svg-png.py
import sys
import subprocess

def convert(input_file, output_file, format='png'):
    cmd = ['mmdc', '-i', input_file, '-o', output_file]
    if format == 'png':
        cmd.extend(['-b', 'transparent'])
    subprocess.run(cmd, check=True)

if __name__ == '__main__':
    convert(sys.argv[1], sys.argv[2])

Core Diagram Types

1. Flowchart

Process flows and decision trees.

flowchart TD
    Start([Start]) --> Input[Input Data]
    Input --> Process{Valid?}
    Process -->|Yes| Calculate[Calculate]
    Process -->|No| Error[Handle Error]
    Calculate --> Output[Output Result]
    Error --> Output
    Output --> End([End])

    style Start fill:#90EE90
    style End fill:#FFB6C6

2. Sequence Diagram

Actor interactions and API flows.

sequenceDiagram
    participant User
    participant API
    participant DB

    User->>API: POST /login
    API->>DB: Validate User
    DB-->>API: User Record
    API-->>User: Token

    alt Success
        User->>API: GET /data
        API-->>User: Data
    else Error
        User->>API: GET /data
        API-->>User: 401 Unauthorized
    end

3. Class Diagram

OOP architecture and data modeling.

classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }

    class Order {
        +int id
        +Date date
        +process()
    }

    User "1" --> "*" Order : places

4. Entity Relationship (ER)

Database schema and relationships.

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "included in"

    USER {
        int id PK
        string email
    }

    ORDER {
        int id PK
        int user_id FK
    }

5. Gantt Chart

Project timelines and schedules.

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Phase 1
    Design :a1, 2024-01-01, 30d
    Dev    :after a1, 60d

    section Phase 2
    Review :2024-04-01, 15d
    Deploy :milestone, 2024-04-15, 0d

6. State Diagram

State machines and lifecycle.

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

7. C4 Architecture

System context and container diagrams.

C4Context
    title System Context
    Person(user, "User", "Uses system")
    System(system, "System", "Core functionality")
    System_Ext(mail, "Email System", "Sends notifications")

    Rel(user, system, "Uses")
    Rel(system, mail, "Sends emails")

8. Git Graph

Version control history.

gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit tag: "v1.0"

9. Mindmap

Hierarchical knowledge structure.

mindmap
  root((Project))
    Planning
      Requirements
      Timeline
    Development
      Frontend
      Backend
    Deployment
      CI/CD
      Monitoring

10. User Journey

User experience flows.

journey
    title User Onboarding
    section Sign Up
      Register: 5: User
      Verify Email: 3: User
    section Setup
      Profile: 4: User
      First Project: 5: User

Advanced Features

Styling & Theming

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ff0000'}}}%%
graph TD
    A[Custom Color]

Subgraphs

graph TB
    subgraph Backend
        API --> DB
    end
    subgraph Frontend
        UI --> API
    end

Best Practices

1. Keep it Simple: Limit nodes to <20 for readability.
2. Direction: Use TD (Top-Down) for hierarchies, LR (Left-Right) for flows.
3. Styling: Use classes for consistent styling across nodes.
4. Version Control: Commit .mmd files, generate images in CI.

Validation Checklist

• Syntax valid (renders in editor)
• Direction appropriate for content
• Labels clear and concise
• Colors used for semantic meaning
• Complex logic broken into subgraphs

Related Skills

• moai-project-documentation: Documentation standards
• moai-domain-frontend: UI visualization
• moai-domain-backend: API & DB modeling

Last Updated: 2025-11-20