Mermaid Diagram Support for Cloudurable Blog

Overview

Mermaid diagram support has been added to the Cloudurable blog. This allows you to create various types of diagrams directly in your markdown files using simple text-based syntax.

How to Use

Basic Usage

Simply create a code block with the language identifier mermaid:

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

Supported Diagram Types

  1. Flowcharts (graph or flowchart)
  2. Sequence Diagrams (sequenceDiagram)
  3. Class Diagrams (classDiagram)
  4. State Diagrams (stateDiagram-v2)
  5. Entity Relationship Diagrams (erDiagram)
  6. Gantt Charts (gantt)
  7. Pie Charts (pie)
  8. Git Graphs (gitGraph)
  9. User Journey Maps (journey)

Examples

Architecture Diagram

graph TB
    subgraph "AWS Region"
        ALB[Application Load Balancer]
        subgraph "Public Subnet"
            EC2_1[EC2 Instance 1]
            EC2_2[EC2 Instance 2]
        end
        subgraph "Private Subnet"
            RDS[(RDS Database)]
            CACHE[(ElastiCache)]
        end
    end
    
    USER[Users] --> ALB
    ALB --> EC2_1
    ALB --> EC2_2
    EC2_1 --> RDS
    EC2_2 --> RDS
    EC2_1 --> CACHE
    EC2_2 --> CACHE

Cassandra Ring Architecture

graph LR
    subgraph "Cassandra Ring"
        N1[Node 1<br/>Token: 0]
        N2[Node 2<br/>Token: 2^63]
        N3[Node 3<br/>Token: 2^64]
        N4[Node 4<br/>Token: 3*2^63]
        
        N1 --> N2
        N2 --> N3
        N3 --> N4
        N4 --> N1
    end
    
    Client[Client] --> N1
    Client --> N2
    Client --> N3
    Client --> N4

API Flow

sequenceDiagram
    participant Client
    participant Gateway
    participant Service
    participant Database
    
    Client->>Gateway: HTTP Request
    Gateway->>Gateway: Validate JWT
    Gateway->>Service: Forward Request
    Service->>Database: Query Data
    Database-->>Service: Return Results
    Service-->>Gateway: Response
    Gateway-->>Client: HTTP Response

Styling

The diagrams are styled to match the blog’s theme with:

  • Light background (#f9f9f9)
  • Rounded corners
  • Responsive sizing
  • Mobile-friendly display
  • Print-optimized styles

Technical Details

Implementation

  • Uses Mermaid.js v10 from CDN
  • Client-side rendering
  • Automatic initialization on page load
  • Custom theme variables for consistent styling

Files Modified

  1. /themes/cloudurable/layouts/partials/scripts.html - Added Mermaid.js script
  2. /themes/cloudurable/static/css/custom.css - Added Mermaid styling

Configuration

The Mermaid configuration in scripts.html includes:

  • Theme variables for colors and styling
  • Flowchart settings for layout
  • Sequence diagram spacing
  • Responsive width handling

Best Practices

  1. Keep diagrams simple - Complex diagrams may be hard to read on mobile
  2. Use meaningful labels - Make node labels descriptive
  3. Add diagram titles - Use headings above diagrams to provide context
  4. Test on mobile - Ensure diagrams are readable on small screens
  5. Provide alternatives - Include text descriptions for accessibility

Troubleshooting

Diagram not rendering?

  1. Check browser console for JavaScript errors
  2. Verify Mermaid syntax using Mermaid Live Editor
  3. Ensure code block language is exactly mermaid
  4. Clear browser cache and reload

Common Issues

  • Syntax errors: Check for missing semicolons or brackets
  • Special characters: Escape quotes and brackets in labels
  • Large diagrams: May need horizontal scrolling on mobile

Testing

A test post has been created at /content/blog/mermaid-diagram-test.md (marked as draft) demonstrating all diagram types.

To preview:

hugo server -D
# Visit http://localhost:1313/blog/mermaid-diagram-test/

Future Enhancements

Possible improvements:

  1. Add dark mode support with theme switching
  2. Create Hugo shortcode for advanced options
  3. Add diagram caching for performance
  4. Implement server-side rendering option
  5. Add diagram export functionality

Resources