Mermaid Diagrams Guide

Welcome to the Mermaid Diagrams Guide! Create beautiful, interactive visualizations directly within your markdown documentation.

🎯 Quick Navigation

Jump directly to what you need:

• 🔄 Flowcharts - Process flows and decision trees
• 💬 Sequence Diagrams - API communications
• 🏛️ Class Diagrams - Component architecture
• ⚡ State Diagrams - Application states
• 🗄️ Database Schemas - Entity relationships
• 📅 Timelines - Gantt charts and planning
• 🌿 Git Workflows - Version control flows
• 🎨 Custom Themes - Brand colors and styling
• 🛠️ Troubleshooting - Common issues and fixes
• 🎨 Styling Guide - CSS custom properties and theming

🎨 What are Mermaid Diagrams?

Mermaid is a powerful diagramming and charting tool that uses simple text syntax to create complex diagrams. Perfect for documentation because diagrams are:

• 📝 Version controllable - Text-based, work great with Git
• 🔄 Always up-to-date - No manual image updates needed
• 🎯 Interactive - Clickable elements and dynamic styling
• 📱 Responsive - Automatically adapt to all screen sizes

🚀 System Architecture Example

Here's your system showing component interactions:

graph TD
    A[Editor-Web] -->|Button Actions| B[Singularity]
    C[Space-Map] -->|Logic Visualization| B
    D[UX-Test] -->|Widget Logic| B
    B -->|Shared Logic| E[Universal Registry]
    B -->|Real-Time Data| F[Smart Database]
    B -->|AI Processing| G[GoGrab-AI]
    F -->|Live Updates| H[Auto Dashboards]
    G -->|Optimizations| B

🔄 Flowcharts

Perfect for: Decision trees, process flows, user journeys

flowchart TD
    Start([Start Documentation]) --> Write[Write Content]
    Write --> Review{Review Content}
    Review -->|Good| Publish[Publish]
    Review -->|Needs Work| Write
    Publish --> End([Complete])

🤖 AI Prompt

Create a Mermaid flowchart for a documentation workflow starting from 'Start Documentation', going through content writing, review process with approval/revision paths, and ending with publication

📋 Copy This Code

```mermaid Your Process Flow
flowchart TD
    Start([Start Documentation]) --> Write[Write Content]
    Write --> Review{Review Content}
    Review -->|Good| Publish[Publish]
    Review -->|Needs Work| Write
    Publish --> End([Complete])
```

🎨 Alternative Layouts

```mermaid Horizontal Process
flowchart LR
    A[Input] --> B[Process] --> C[Output]
    B --> D[Validation]
    D -->|Pass| C
    D -->|Fail| A
```

💬 Sequence Diagrams

Perfect for: API communications, user interactions, system workflows

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database
    
    User->>Frontend: Click Button
    Frontend->>API: POST /api/data
    API->>Database: Query Data
    Database-->>API: Return Results
    API-->>Frontend: JSON Response
    Frontend-->>User: Update UI

🤖 AI Prompt

Generate a Mermaid sequence diagram showing API communication flow between User, Frontend, API, and Database with specific request/response interactions

📋 Copy This Code

```mermaid API Communication
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database
    
    User->>Frontend: Click Button
    Frontend->>API: POST /api/data
    API->>Database: Query Data
    Database-->>API: Return Results
    API-->>Frontend: JSON Response
    Frontend-->>User: Update UI
```

🎨 Authentication Flow Example

```mermaid User Authentication
sequenceDiagram
    participant User
    participant App
    participant AuthService
    participant Database
    
    User->>App: Enter credentials
    App->>AuthService: Validate
    AuthService->>Database: Check user
    Database-->>AuthService: User data
    AuthService-->>App: JWT token
    App-->>User: Login success
```

🏛️ Class Diagrams

Perfect for: Component architecture, object relationships, system structure

classDiagram
    class MarkdownRenderer {
        +parseMarkdown()
        +renderElements()
        +processInlineElements()
    }
    
    class MermaidComponent {
        +renderDiagram()
        +copyDiagram()
        +downloadDiagram()
    }
    
    class CodeBlockComponent {
        +highlightCode()
        +copyCode()
    }
    
    MarkdownRenderer --> MermaidComponent
    MarkdownRenderer --> CodeBlockComponent

🤖 AI Prompt

Create a Mermaid class diagram showing Angular component architecture with MarkdownRenderer, MermaidComponent, and CodeBlockComponent classes, including their methods and relationships

📋 Copy This Code

```mermaid Component Architecture
classDiagram
    class MarkdownRenderer {
        +parseMarkdown()
        +renderElements()
        +processInlineElements()
    }
    
    class MermaidComponent {
        +renderDiagram()
        +copyDiagram()
        +downloadDiagram()
    }
    
    class CodeBlockComponent {
        +highlightCode()
        +copyCode()
    }
    
    MarkdownRenderer --> MermaidComponent
    MarkdownRenderer --> CodeBlockComponent
```

⚡ State Diagrams

Perfect for: Application states, workflow transitions, status management

stateDiagram-v2
    [*] --> Loading
    Loading --> Ready : Data Loaded
    Loading --> Error : Load Failed
    Ready --> Processing : User Action
    Processing --> Ready : Success
    Processing --> Error : Failure
    Error --> Loading : Retry
    Ready --> [*] : Shutdown

🤖 AI Prompt

Generate a Mermaid state diagram for an application with states: Loading, Ready, Processing, Error. Include transitions for data loading, user actions, success/failure paths, and retry mechanism

📋 Copy This Code

```mermaid Application States
stateDiagram-v2
    [*] --> Loading
    Loading --> Ready : Data Loaded
    Loading --> Error : Load Failed
    Ready --> Processing : User Action
    Processing --> Ready : Success
    Processing --> Error : Failure
    Error --> Loading : Retry
    Ready --> [*] : Shutdown
```

🗄️ Database Schemas

Perfect for: Entity relationships, database design, data modeling

erDiagram
    User ||--o{ Document : creates
    User ||--o{ Comment : writes
    Document ||--o{ Comment : contains
    Document ||--o{ Tag : has
    
    User {
        string id PK
        string name
        string email
        datetime created_at
    }
    
    Document {
        string id PK
        string title
        text content
        string user_id FK
        datetime created_at
    }

🤖 AI Prompt

Create a Mermaid entity relationship diagram for a documentation system with User, Document, Comment, and Tag entities. Include primary keys, foreign keys, and relationship cardinalities

📋 Copy This Code

```mermaid Database Schema
erDiagram
    User ||--o{ Document : creates
    User ||--o{ Comment : writes
    Document ||--o{ Comment : contains
    Document ||--o{ Tag : has
    
    User {
        string id PK
        string name
        string email
        datetime created_at
    }
    
    Document {
        string id PK
        string title
        text content
        string user_id FK
        datetime created_at
    }
```

🎨 Dark Theme Variant

```mermaid Database Schema Dark
%%{init: {'theme':'dark'}}%%
erDiagram
    User ||--o{ Document : creates
    User ||--o{ Comment : writes
    Document ||--o{ Comment : contains
    Document ||--o{ Tag : has
    
    User {
        string id PK
        string name
        string email
        datetime created_at
    }
```

📅 Project Timelines

Perfect for: Project planning, task scheduling, milestone tracking

gantt
    title Documentation Project Timeline
    dateFormat  YYYY-MM-DD
    section Analysis
    Requirements     :done, req, 2024-01-01, 2024-01-07
    Research         :done, research, after req, 3d
    section Development
    Setup            :done, setup, 2024-01-08, 2024-01-10
    Core Features    :active, core, 2024-01-11, 2024-01-25
    Mermaid Support  :active, mermaid, 2024-01-20, 2024-01-30
    section Testing
    Unit Tests       :testing, 2024-01-26, 2024-02-05
    Integration      :integration, after testing, 5d

🤖 AI Prompt

Create a Mermaid Gantt chart for a documentation project with Analysis, Development, and Testing phases. Include specific tasks with done/active/pending states and realistic timeline from January to February 2024

📋 Copy This Code

```mermaid Project Timeline
gantt
    title My Project Timeline
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements    :done, req, 2024-01-01, 2024-01-07
    Design          :done, design, after req, 5d
    section Development  
    Backend         :active, backend, 2024-01-15, 2024-02-01
    Frontend        :frontend, after backend, 2024-02-15
    section Testing
    Unit Tests      :testing, after frontend, 10d
    Integration     :integration, after testing, 7d
```

7. Git Flow

Version control workflows:

gitGraph
    commit id: "Initial"
    branch feature/mermaid
    checkout feature/mermaid
    commit id: "Add component"
    commit id: "Add parsing"
    commit id: "Add styles"
    checkout main
    commit id: "Other changes"
    merge feature/mermaid
    commit id: "Deploy"

🤖 AI Prompt:

"Generate a Mermaid gitGraph showing a feature branch workflow with initial commit, feature branch creation, multiple commits on feature branch, parallel main branch changes, and merge back to main"

📋 Copy This Code

```mermaid Git Workflow
gitGraph
    commit id: "Initial"
    branch "feature/your-feature"
    checkout "feature/your-feature"
    commit id: "Add feature"
    commit id: "Add tests"
    commit id: "Fix bugs"
    checkout main
    commit id: "Other changes"
    merge "feature/your-feature"
    commit id: "Deploy"
```

🎨 Custom Themes

Perfect for: Brand consistency, custom styling, professional appearance

%%{init: {'theme':'dark'}}%%
graph LR
    A[Dark Theme] --> B[Beautiful]
    B --> C[Professional]
    C --> D[Modern]

🤖 AI Prompt

Create a Mermaid flowchart with dark theme showing a progression from 'Dark Theme' to 'Beautiful' to 'Professional' to 'Modern' using horizontal layout

📋 Copy This Code

```mermaid Dark Theme Example
%%{init: {'theme':'dark'}}%%
graph LR
    A[Dark Theme] --> B[Beautiful]
    B --> C[Professional]  
    C --> D[Modern]
```

🌈 More Theme Examples

```mermaid Custom Brand Colors
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#1f2937',
    'primaryBorderColor': '#3b82f6',
    'lineColor': '#6b7280'
  }
}}%%
graph TD
    A[Your App] --> B[Your Service]
    B --> C[Your Database]
```

🛠️ Troubleshooting

🚨 Common Parsing Errors

Special Characters in Node Labels

Error: Parse error... got 'LINK_ID' Cause: Special characters like @, /, - in node labels

❌ Wrong:

graph TD
    A[My App] --> B[@theme-runtime]

✅ Correct:

graph TD
    A["My App"] --> B["@theme-runtime"]

💡 Quick Tips

1. Test First - Use mermaid.live to validate syntax
2. Quote Special Characters - Always quote labels with @, /, or spaces
3. Keep IDs Simple - Use letters (A, B, C) for node IDs
4. Check Console - Browser shows detailed parsing errors

🔧 Syntax Reference

Node Shapes:

• A[Rectangle] - Rectangular nodes
• B(Rounded) - Rounded rectangles
• C{Diamond} - Decision points
• D([Stadium]) - Start/end points

Arrow Types:

• --> - Solid arrow
• -.-> - Dotted arrow
• ==> - Thick arrow

🤖 AI Agent Quick Guide

Best AI Prompts

"Create a Mermaid [TYPE] diagram for [YOUR_SYSTEM] showing [COMPONENTS] with [RELATIONSHIPS]. Use proper syntax with quoted labels for special characters like @, /, and spaces."

Example Conversation

• You: "Create a Mermaid sequence diagram for our checkout process with User, Frontend, PaymentAPI, Database"
• AI: [Generates working Mermaid code]

📚 Resources & Help

🔗 Official Links

• Mermaid Documentation
• Live Editor - Test your diagrams
• Theming Guide

✅ Final Checklist

• Diagram type matches your needs (flowchart, sequence, etc.)
• All special characters are quoted: ["@theme"]
• Tested in mermaid.live
• AI prompt ready for future modifications

🎨 Need Custom Styling?

For complete control over diagram appearance, colors, and branding:

👉 Visit the Styling Guide - Comprehensive guide with CSS custom properties, ready-to-use themes, and simple solutions for perfect visual hierarchy.

🎉 Start creating beautiful diagrams today! 📊✨