The @docmd/plugin-mermaid plugin integrates the powerful Mermaid.js engine into your documentation pipeline. It allows you to transform plain-text descriptions into high-fidelity, interactive diagrams without ever leaving your Markdown environment.

Key Features

• Zero Scripting: No need to manually include external scripts or CDN links. docmd detects the usage and injects the rendering engine only where needed.
• Theme Awareness: Diagrams automatically adapt their color schemes to match your site’s Light or Dark mode transitions.
• Isomorphic Lazy Loading: For optimum performance, diagrams are initialized and rendered only as they enter the user’s viewport.
• Technical Readability: Diagrams remain pure text in your source, making them easily version-controlled and readable by AI agents.

Configuration

To enable diagram support, add the mermaid plugin to your docmd.config.js:

import { defineConfig } from '@docmd/core';

export default defineConfig({
  plugins: {
    mermaid: {} // Enabled with zero-config
  }
});

Implementation Gallery

To render a diagram, place your Mermaid syntax within a fenced code block with the mermaid language identifier.

1. Sequence Diagrams

Ideal for illustrating interactions between multiple system components.

```mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server
    
    User->>Browser: Enters URL
    Browser->>Server: HTTP Request
    Server-->>Browser: HTTP Response
    Browser-->>User: Displays Page
```

2. Analytical Charts

Visualize data using built-in chart types like Pie Charts or Bar Charts.

```mermaid
pie title Project Composition
    "Documentation" : 45
    "Core Engine" : 30
    "Plugins" : 15
    "UI Components" : 10
```

3. Git Workflows

Visualize branching and merging strategies for your developer guides.

```mermaid
gitGraph
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
```

Technical Implementation

The Mermaid plugin operates by intercepting mermaid code blocks during the parsing phase and wrapping them in a specialized <div class="mermaid"> container.

1. Detection: The engine scans the rendered HTML for the presence of mermaid containers.
2. Asset Injection: If containers are found, docmd injects a lightweight init-mermaid.js module.
3. Rendering: The Mermaid library is fetched asynchronously and renders the diagrams client-side, ensuring that your initial HTML payload remains small and fast.