Create UML Diagrams using Mermaid

Recently, I revamped my website to focus more on blogs. This included adding a search bar to enhance user navigation through my content.

In this post, I’ll guide you through the process of adding your own interactive UML Diagrams to an Astro project using Mermaid!

The complete UML Component

To get started, let’s create a reusable UML diagram component in Astro. Below is the implementation of the UML component that will render the Mermaid diagrams:

You will need to create a componet UMLDiagram.astro and then import in your md or mdx file.

---
interface Props {
  code?: string;
  title?: string;
  caption?: string;
}

const {
  code = `
    classDiagram
    class Example {
      +String data
      +update() void
    }
  `,
  title = "",
  caption = ""
} = Astro.props;

---

<div class="w-full max-w-4xl mx-auto p-4">
  {title && (
    <h3 class="text-xl font-semibold mb-4 text-gray-800">
      {title}
    </h3>
  )}
  
  <div class="relative bg-white rounded-lg shadow-md overflow-hidden">
    <div class="mermaid p-6 bg-gray-50">
      {code.trim()}
    </div>
  </div>

  {caption && (
    <p class="mt-2 text-sm text-gray-600 italic">
      {caption}
    </p>
  )}
</div>

<!-- Load mermaid from CDN -->
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  declare const mermaid: any;
  
  // Initialize mermaid
  mermaid.initialize({
    startOnLoad: true,
    theme: 'default',
    securityLevel: 'loose',
    htmlLabels: true,
    flowchart: {
      useMaxWidth: true,
      htmlLabels: true,
      curve: 'basis'
    }
  });
</script>

Basic Setup

Installation

To begin using Mermaid in your Astro project, you will need to install it.

Execute the following command based on your package manager:

Using npm:

npm install mermaid

Using yarn:

yarn add mermaid

Breakdown of the Functionality

The UML component allows you to specify a diagram via a textual description using the Mermaid syntax. This component will handle rendering, styling, and initialization of Mermaid diagrams:

Here’s how the props work:

• code: The Mermaid code that defines your UML diagram.

• title: An optional title for your diagram.

• caption: An optional caption that provides additional context.

Props Interface and Default Values

---
interface Props {
  code?: string;
  title?: string;
  caption?: string;
}

const {
  code = `
    classDiagram
    class Example {
      +String data
      +update() void
    }
  `,
  title = "",
  caption = ""
} = Astro.props;

---

This section defines the TypeScript interface for our props and sets up default values.

The default code prop gives you a simple class diagram in case you forget to specify one.

Component Layout

<div class="w-full max-w-4xl mx-auto p-4">
  {title && (
    <h3 class="text-xl font-semibold mb-4 text-gray-800">
      {title}
    </h3>
  )}
  
  <div class="relative bg-white rounded-lg shadow-md overflow-hidden">
    <div class="mermaid p-6 bg-gray-50">
      {code.trim()}
    </div>
  </div>

  {caption && (
    <p class="mt-2 text-sm text-gray-600 italic">
      {caption}
    </p>
  )}
</div>

The layout section:

Mermaid Initialization

Now it’s time to put everything together with Mermaid’s initialization:

<!-- Load mermaid from CDN -->
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  declare const mermaid: any;
  
  // Initialize mermaid
  mermaid.initialize({
    startOnLoad: true,
    theme: 'default',
    securityLevel: 'loose',
    htmlLabels: true,
    flowchart: {
      useMaxWidth: true,
      htmlLabels: true,
      curve: 'basis'
    }
  });
</script>

Example

Below is an example of how to render a UML diagram within your Astro application:

<UMLDiagram
  title="UML Demo: Modern E-commerce Architecture"
  code={`sequenceDiagram
    participant Customer
    participant API Gateway
    participant Auth Service
    participant Order Service
    participant Payment Service
    participant Inventory
    participant Notification
    
    rect rgb(240, 248, 255)
        Note over Customer,Notification: Purchase Flow
        Customer->>+API Gateway: Add to Cart
        API Gateway->>+Auth Service: Validate Session
        Auth Service-->>-API Gateway: Session Valid
        API Gateway->>+Inventory: Check Stock
        Inventory-->>-API Gateway: In Stock
        API Gateway-->>Customer: Item Added
    end

    rect rgb(255, 245, 238)
        Note over Customer,Notification: Checkout Process
        Customer->>+API Gateway: Checkout
        API Gateway->>+Order Service: Create Order
        Order Service->>+Payment Service: Process Payment
        
        par Parallel Processes
            Payment Service->>Payment Service: Validate Card
            Payment Service->>Payment Service: Security Checks
        end
        
        Payment Service-->>-Order Service: Payment Success
        Order Service->>Inventory: Update Stock
        Order Service-->>-API Gateway: Order Confirmed
        API Gateway->>+Notification: Send Confirmation
        Notification->>Notification: Generate Email
        Notification->>Customer: Order Details
        Note over Customer: Happy Customer! 🎉
    end`}
  caption="A comprehensive sequence diagram showing the flow of a modern e-commerce system using microservices architecture. It demonstrates cart operations, checkout process, and order confirmation flow."
/>

Wrapping Up

Integrating UML diagrams into your Astro project with Mermaid, you can enhance your documentation and make complex concepts easier to understand. These diagrams can be customized with Mermaid’s extensive syntax, allowing for a range of diagram types beyond just UML.

Feel free to experiment with different diagram types and styles to find what best suits your project’s needs. :D

Disclaimer: This post is for personal use, but I hope it can also help others. I'm sharing my thoughts and experiences here.

If you have any insights or feedback, please reach out!

Note: Some content on this site may have been formatted using AI.