Skip to main content

​
Mermaid Plugin

The Mermaid plugin enables rendering of Mermaid diagrams directly in your markdown documentation.

​
Features

  • Simple Syntax - Use standard Mermaid code blocks
  • All Diagram Types - Flowcharts, sequence diagrams, class diagrams, and more
  • Automatic Rendering - Converts code blocks to interactive diagrams
  • Theme Integration - Respects your site’s light/dark theme

​
Configuration

The plugin is automatically enabled:
packages/doom/src/plugins/mermaid/index.ts:5-12
export const mermaidPlugin = (): RspressPlugin => {
  return {
    name: 'doom-mermaid',
    markdown: {
      remarkPlugins: [remarkMermaid],
    },
  }
}

​
Usage

Create diagrams using Mermaid code blocks: 
```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

​
Diagram Types

​
Flowcharts

Create flowcharts to visualize processes: 
```mermaid
graph LR
    A[User] --> B[Login]
    B --> C{Authenticated?}
    C -->|Yes| D[Dashboard]
    C -->|No| E[Error]
    E --> B
```

​
Sequence Diagrams

Document interactions between systems: 
```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database
    
    Client->>API: Request Data
    API->>Database: Query
    Database-->>API: Results
    API-->>Client: Response
```

​
Class Diagrams

Show object-oriented structure: 
```mermaid
classDiagram
    class Plugin {
        +String name
        +init()
        +execute()
    }
    class AutoSidebarPlugin {
        +scanDirectory()
        +generateConfig()
    }
    Plugin <|-- AutoSidebarPlugin
```

​
State Diagrams

Visualize state machines: 
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Success: Complete
    Processing --> Failed: Error
    Success --> [*]
    Failed --> Idle: Retry
```

​
Entity Relationship Diagrams

Document database schemas: 
```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
    
    USER {
        string id
        string name
        string email
    }
    ORDER {
        string id
        date created_at
        string status
    }
```

​
Gantt Charts

Create project timelines: 
```mermaid
gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Design           :a1, 2024-01-01, 30d
    Development      :after a1, 60d
    section Phase 2
    Testing          :2024-04-01, 20d
    Deployment       :2024-04-21, 10d
```

​
Pie Charts

Display proportions: 
```mermaid
pie title Plugin Usage
    "Auto Sidebar" : 35
    "API" : 25
    "Mermaid" : 20
    "Directives" : 15
    "Other" : 5
```

​
Implementation

The plugin transforms Mermaid code blocks into React components:
packages/doom/src/plugins/mermaid/remark-mermaid.ts:5-25
export const remarkMermaid: Plugin<[], Root> = function () {
  return (root) => {
    visit(root, 'code', (node, index, parent) => {
      if (!parent || node.lang !== 'mermaid') {
        return
      }
      parent.children.splice(index!, 1, {
        type: 'mdxJsxFlowElement',
        name: 'Mermaid',
        attributes: [
          {
            type: 'mdxJsxAttribute',
            name: 'children',
            value: node.value,
          },
        ],
        children: [],
      })
    })
  }
}

​
Advanced Features

​
Custom Styling

Customize Mermaid diagram appearance: 
```mermaid
%%{init: {'theme':'dark'}}%%
graph TD
    A[Dark Theme] --> B[Custom Colors]
```

​
Configuration

Add Mermaid configuration: 
```mermaid
%%{init: {'flowchart': {'curve': 'basis'}}}%%
graph LR
    A --> B --> C
```

​
Notes and Comments

Add documentation to your diagrams: 
```mermaid
graph TD
    A[Start] --> B[Process]
    %% This is a comment
    B --> C[End]
```

​
Best Practices

  1. Keep It Simple - Complex diagrams are hard to read
  2. Use Labels - Add descriptive text to nodes and edges
  3. Consistent Direction - Use TD (top-down) or LR (left-right) consistently
  4. Test Rendering - Preview diagrams before committing
  5. Add Context - Include explanatory text around diagrams

​
Common Use Cases

​
Architecture Diagrams

​
Deployment Flow

​
Plugin Lifecycle

​
Troubleshooting

​
Diagram Not Rendering

Ensure:
  • Code block uses mermaid language identifier
  • Syntax is valid (test on mermaid.live)
  • No conflicting plugins

​
Syntax Errors

Validate your diagram:
  1. Copy diagram code
  2. Test on mermaid.live
  3. Fix syntax errors
  4. Update your docs

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us