tools-mermaid

# Mermaid Diagrams ## Overview Mermaid is a markdown-based diagramming tool that renders in GitHub, GitLab, Notion, and documentation sites. Use this skill to create visual diagrams in markdown files. ## When to Use - Documenting system architecture - Visualizing API flows and sequences - Creating database ER diagrams - Illustrating state machines - Project timelines and Gantt charts - Git branch strategies ## Basic Syntax ````markdown ```mermaid flowchart LR A --> B --> C ``` ```` ## Flowcharts ### Direction ``` flowchart TB %% Top to Bottom flowchart BT %% Bottom to Top flowchart LR %% Left to Right flowchart RL %% Right to Left ``` ### Node Shapes ```mermaid flowchart LR A[Rectangle] B(Rounded) C([Stadium]) D[[Subroutine]] E[(Database)] F((Circle)) G>Flag] H{Diamond} I{{Hexagon}} J[/Parallelogram/] K[\Parallelogram Alt\] L[/Trapezoid\] ``` ### Connections ```mermaid flowchart LR A --> B %% Arrow A --- B %% Line A -.-> B %% Dotted arrow A ==> B %% Thick arrow A --text--> B %% Arrow with text A -->|text| B %% Alt text syntax A <--> B %% Bidirectional ``` ### Subgraphs ```mermaid flowchart TB subgraph Frontend A[React App] B[Next.js] end subgraph Backend C[API Server] D[(Database)] end A --> C B --> C C --> D ``` ### Styling ```mermaid flowchart LR A[Start]:::green --> B[Process]:::blue --> C[End]:::red classDef green fill:#9f6,stroke:#333 classDef blue fill:#69f,stroke:#333 classDef red fill:#f66,stroke:#333 ``` ## Sequence Diagrams ### Basic Sequence ```mermaid sequenceDiagram participant U as User participant A as API participant D as Database U->>A: POST /login A->>D: Query user D-->>A: User data A-->>U: JWT token ``` ### Arrow Types ``` ->> Solid arrow -->> Dotted arrow -x Solid cross (async) --x Dotted cross -) Open arrow --) Dotted open arrow ``` ### Activations & Notes ```mermaid sequenceDiagram participant C as Client participant S as Server C->>+S: Request Note right of S: Processing... S-->>-C: Response Note over C,S: Connection established ``` ### Loops & Conditionals ```mermaid sequenceDiagram participant C as Client participant S as Server loop Every 30s C->>S: Heartbeat end alt Success S-->>C: 200 OK else Error S-->>C: 500 Error end opt Optional Step C->>S: Analytics end ``` ## Entity Relationship Diagrams ```mermaid erDiagram USER ||--o{ ORDER : places USER { int id PK string email UK string name datetime created_at } ORDER ||--|{ ORDER_ITEM : contains ORDER { int id PK int user_id FK decimal total string status } ORDER_ITEM { int id PK int order_id FK int product_id FK int quantity } PRODUCT ||--o{ ORDER_ITEM : "ordered in" PRODUCT { int id PK string name decimal price } ``` ### Relationship Types ``` ||--|| One to one ||--o{ One to many }o--o{ Many to many ||--|{ One to one or many ``` ## State Diagrams ```mermaid stateDiagram-v2 [*] --> Draft Draft --> Review: Submit Review --> Draft: Request Changes Review --> Approved: Approve Approved --> Published: Publish Published --> [*] state Review { [*] --> Pending Pending --> InProgress: Assign InProgress --> Complete: Finish Complete --> [*] } ``` ### Transitions & Notes ```mermaid stateDiagram-v2 [*] --> Active Active --> Inactive: timeout Inactive --> Active: wake Active --> [*]: terminate note right of Active: Processing requests note left of Inactive: Sleeping ``` ## Class Diagrams ```mermaid classDiagram class User { +int id +string email +string name +login() +logout() } class Order { +int id +decimal total +string status +calculate() +submit() } class Product { +int id +string name +decimal price } User "1" --> "*" Order: places Order "*" --> "*" Product: contains ``` ### Visibility & Relationships ``` + Public - Private # Protected ~ Package <|-- Inheritance *-- Composition o-- Aggregation --> Association ..> Dependency ..|> Realization ``` ## Gantt Charts ```mermaid gantt title Project Timeline dateFormat YYYY-MM-DD section Planning Requirements :a1, 2024-01-01, 7d Design :a2, after a1, 5d section Development Backend API :b1, after a2, 14d Frontend :b2, after a2, 14d Integration :b3, after b1, 7d section Testing QA Testing :c1, after b3, 7d UAT :c2, after c1, 5d section Launch Deployment :milestone, after c2, 0d ``` ## Git Graphs ```mermaid gitGraph commit id: "Initial" branch develop checkout develop commit id: "Feature A" commit id: "Feature B" checkout main merge develop id: "Release 1.0" branch hotfix commit id: "Fix bug" checkout main merge hotfix id: "Patch 1.0.1" ``` ## Pie Charts ```mermaid pie showData title Browser Market Share "Chrome" : 65 "Safari" : 19 "Firefox" : 10 "Edge" : 4 "Other" : 2 ``` ## Mindmaps ```mermaid mindmap root((Project)) Frontend React TypeScript Tailwind Backend Node.js PostgreSQL Redis DevOps Docker Kubernetes CI/CD ``` ## Timeline ```mermaid timeline title Product Roadmap section Q1 January : Feature A : Feature B February : Feature C March : Release 1.0 section Q2 April : Feature D May : Feature E : Feature F June : Release 2.0 ``` ## Common Patterns ### API Flow ```mermaid sequenceDiagram participant C as Client participant G as API Gateway participant A as Auth Service participant S as Service participant D as Database C->>G: Request + Token G->>A: Validate Token A-->>G: Valid G->>S: Forward Request S->>D: Query D-->>S: Data S-->>G: Response G-->>C: Response ``` ### Microservices Architecture ```mermaid flowchart TB subgraph Client Web[Web App] Mobile[Mobile App] end subgraph Gateway AG[API Gateway] LB[Load Balancer] end subgraph Services US[User Service] OS[Order Service] PS[Product Service] NS[Notification Service] end subgraph Data UD[(User DB)] OD[(Order DB)] PD[(Product DB)] MQ[Message Queue] end Web --> LB Mobile --> LB LB --> AG AG --> US & OS & PS US --> UD OS --> OD PS --> PD OS --> MQ MQ --> NS ``` ### CI/CD Pipeline ```mermaid flowchart LR subgraph Source GH[GitHub] end subgraph CI Build[Build] Test[Test] Lint[Lint] end subgraph CD Stage[Staging] Prod[Production] end GH -->|push| Build Build --> Test & Lint Test & Lint -->|pass| Stage Stage -->|approve| Prod ``` ## Tips - Use `%%` for comments - Keep diagrams focused (split large ones) - Test rendering in GitHub/target platform - Use meaningful IDs for nodes - Leverage subgraphs for organization ## Rendering | Platform | Support | |----------|---------| | GitHub | ✅ Native in `.md` files | | GitLab | ✅ Native in `.md` files | | Notion | ✅ Code block type "mermaid" | | VS Code | ✅ With extension | | Docusaurus | ✅ Plugin available | | Obsidian | ✅ Native support |