✓ Verified 📁 File Management ✓ Enhanced Data

Beautiful Mermaid

Render beautiful Mermaid diagrams as SVGs or ASCII art.

Rating: 4 (305 reviews)
Downloads: 1,165 downloads
Version: 1.0.0

Overview

Render beautiful Mermaid diagrams as SVGs or ASCII art.

Complete Documentation

View Source →

Beautiful Mermaid

Render Mermaid diagrams as beautiful SVGs or ASCII art. Ultra-fast, fully themeable, zero DOM dependencies. Built for the AI era.

When to Use

Use this skill when:

User sends Mermaid code blocks (\\\mermaid ... \\\)
User asks to "render" or "visualize" a diagram
User wants terminal/ASCII output for diagrams
User needs themed diagrams (15 built-in themes)
User wants SVG output for rich UIs

Installation

bash

npm install beautiful-mermaid
# or
bun add beautiful-mermaid
# or
pnpm add beautiful-mermaid

Quick Start

SVG Output (Default)

typescript

import { renderMermaid } from 'beautiful-mermaid'

const svg = await renderMermaid(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)

ASCII Output (Terminal)

typescript

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)

Output:

text

┌───┐     ┌───┐     ┌───┐
│   │     │   │     │   │
│ A │────►│ B │────►│ C │
│   │     │   │     │   │
└───┘     └───┘     └───┘

Supported Diagrams

Type	Syntax	Description
Flowchart	graph TD/LR/BT/RL	All directions supported
State	stateDiagram-v2	State machine diagrams
Sequence	sequenceDiagram	Sequence/interaction diagrams
Class	classDiagram	Class inheritance diagrams
ER	erDiagram	Entity-relationship diagrams

Flowchart Example

\\\mermaid graph TD A[Start] --> B{Decision} B -->|Yes| C[Action] B -->|No| D[End] C --> D \\\

Sequence Example

\\\mermaid sequenceDiagram Alice->>Bob: Hello Bob! Bob-->>Alice: Hi Alice! \\\

Theming System

Built-in Themes (15)

typescript

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// Use a built-in theme
const svg = await renderMermaid(diagram, THEMES['tokyo-night'])

// Available themes:
THEMES['zinc-light']
THEMES['zinc-dark']
THEMES['tokyo-night']
THEMES['tokyo-night-storm']
THEMES['tokyo-night-light']
THEMES['catppuccin-mocha']
THEMES['catppuccin-latte']
THEMES['nord']
THEMES['nord-light']
THEMES['dracula']
THEMES['github-light']
THEMES['github-dark']
THEMES['solarized-light']
THEMES['solarized-dark']
THEMES['one-dark']

Custom Theme (Mono Mode)

typescript

// Just two colors - the system derives everything
const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',  // Background
  fg: '#a9b1d6',  // Foreground
})

Enriched Theme

typescript

const svg = await renderMermaid(diagram, {
  bg: '#1a1b26',
  fg: '#a9b1d6',
  line: '#3d59a1',    // Edge color
  accent: '#7aa2f7',  // Arrow heads
  muted: '#565f89',   // Secondary text
  surface: '#292e42', // Node fill
  border: '#3d59a1',  // Node stroke
})

Shiki Theme Compatibility

typescript

import { renderMermaid, fromShikiTheme } from 'beautiful-mermaid'
import { getHighlighter } from 'shiki'

const highlighter = await getHighlighter({ theme: 'vitesse-dark' })
const colors = fromShikiTheme(highlighter.getTheme('vitesse-dark'))
const svg = await renderMermaid(diagram, colors)

ASCII/Unicode Output

For terminal environments:

typescript

import { renderMermaidAscii } from 'beautiful-mermaid'

// Unicode (prettier, default)
const unicode = renderMermaidAscii(`graph LR; A --> B`)

// Pure ASCII (maximum compatibility)
const ascii = renderMermaidAscii(`graph LR; A --> B`, { useAscii: true })

// Custom spacing
renderMermaidAscii(diagram, {
  useAscii: false,
  paddingX: 5,          // Horizontal spacing
  paddingY: 5,          // Vertical spacing
  boxBorderPadding: 1,  // Inner padding
})

API Reference

renderMermaid(text, options?): Promise

Render Mermaid to SVG.

Options:

Option	Type	Default	Description
bg	string	#FFFFFF	Background color
fg	string	#27272A	Foreground color
line	string?	—	Edge color
accent	string?	—	Arrow heads, highlights
muted	string?	—	Secondary text
surface	string?	—	Node fill tint
border	string?	—	Node stroke
font	string	Inter	Font family
transparent	boolean	false	Transparent background

renderMermaidAscii(text, options?): string

Render Mermaid to ASCII/Unicode. Synchronous.

Options:

Option	Type	Default	Description
useAscii	boolean	false	Use ASCII instead of Unicode
paddingX	number	5	Horizontal node spacing
paddingY	number	5	Vertical node spacing
boxBorderPadding	number	1	Inner box padding

THEMES: Record

All 15 built-in themes.

fromShikiTheme(theme): DiagramColors

Extract diagram colors from Shiki theme.

Usage in OpenClaw

Telegram Integration

For Telegram, render as SVG and send as photo:

typescript

import { renderMermaid } from 'beautiful-mermaid'

async function sendMermaid(message: string) {
  const blocks = extractMermaidBlocks(message)
  
  for (const block of blocks) {
    const svg = await renderMermaid(block.code, THEMES['tokyo-night'])
    // Send SVG as photo to Telegram
  }
}

Terminal/CLI Output

typescript

import { renderMermaidAscii } from 'beautiful-mermaid'

function printDiagram(code: string) {
  const ascii = renderMermaidAscii(code)
  console.log(ascii)
}

Performance

100+ diagrams in under 500ms
Zero DOM dependencies - pure TypeScript
Ultra-fast - no browser/Puppeteer needed

Comparison to Alternatives

Feature	beautiful-mermaid	mmdc
Dependencies	Zero DOM	Puppeteer
Speed	<500ms for 100+ diagrams	Slower
ASCII output	✅ Native	❌ No
Themes	15 built-in + Shiki	CSS
Size	Lightweight	Heavy

Example Workflow

Input:

text

Here is the system architecture:

\`\`\`mermaid
graph TD
  User --> LB[Load Balancer]
  LB --> API[API Server]
  API --> DB[(Database)]
  API --> Cache
\`\`\`

And the flow:

\`\`\`mermaid
sequenceDiagram
  participant U as User
  participant A as API
  U->>A: Request
  A-->>U: Response
\`\`\`

Action: Render both diagrams with appropriate theme.

Output: Send two SVG images with captions.

Resources

npm: https://www.npmjs.com/package/beautiful-mermaid
GitHub: https://github.com/lukilabs/beautiful-mermaid
Live Demo: https://agents.craft.do/mermaid

Installation

Terminal bash


openclaw install beautiful-mermaid

Copied!

💻Code Examples

pnpm add beautiful-mermaid

pnpm-add-beautiful-mermaid.txt

## Quick Start

### SVG Output (Default)

└───┘ └───┘ └───┘

--.txt

## Supported Diagrams

| Type | Syntax | Description |
|------|--------|-------------|
| Flowchart | `graph TD/LR/BT/RL` | All directions supported |
| State | `stateDiagram-v2` | State machine diagrams |
| Sequence | `sequenceDiagram` | Sequence/interaction diagrams |
| Class | `classDiagram` | Class inheritance diagrams |
| ER | `erDiagram` | Entity-relationship diagrams |

### Flowchart Example

\`\`\`mermaid
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]
  C --> D
\`\`\`

### Sequence Example

\`\`\`mermaid
sequenceDiagram
  Alice->>Bob: Hello Bob!
  Bob-->>Alice: Hi Alice!
\`\`\`

## Theming System

### Built-in Themes (15)

const svg = await renderMermaid(diagram, colors)

const-svg--await-rendermermaiddiagram-colors.txt

## ASCII/Unicode Output

For terminal environments:

})

.txt

## API Reference

### renderMermaid(text, options?): Promise<string>

Render Mermaid to SVG.

**Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `bg` | string | `#FFFFFF` | Background color |
| `fg` | string | `#27272A` | Foreground color |
| `line` | string? | — | Edge color |
| `accent` | string? | — | Arrow heads, highlights |
| `muted` | string? | — | Secondary text |
| `surface` | string? | — | Node fill tint |
| `border` | string? | — | Node stroke |
| `font` | string | `Inter` | Font family |
| `transparent` | boolean | `false` | Transparent background |

### renderMermaidAscii(text, options?): string

Render Mermaid to ASCII/Unicode. Synchronous.

**Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `useAscii` | boolean | `false` | Use ASCII instead of Unicode |
| `paddingX` | number | `5` | Horizontal node spacing |
| `paddingY` | number | `5` | Vertical node spacing |
| `boxBorderPadding` | number | `1` | Inner box padding |

### THEMES: Record<string, DiagramColors>

All 15 built-in themes.

### fromShikiTheme(theme): DiagramColors

Extract diagram colors from Shiki theme.

## Usage in OpenClaw

### Telegram Integration

For Telegram, render as SVG and send as photo:

}

.txt

## Performance

- **100+ diagrams** in under 500ms
- **Zero DOM dependencies** - pure TypeScript
- **Ultra-fast** - no browser/Puppeteer needed

## Comparison to Alternatives

| Feature | beautiful-mermaid | mmdc |
|---------|------------------|------|
| Dependencies | Zero DOM | Puppeteer |
| Speed | <500ms for 100+ diagrams | Slower |
| ASCII output | ✅ Native | ❌ No |
| Themes | 15 built-in + Shiki | CSS |
| Size | Lightweight | Heavy |

## Example Workflow

**Input:**

example.sh

npm install beautiful-mermaid
# or
bun add beautiful-mermaid
# or
pnpm add beautiful-mermaid

example.ts

import { renderMermaid } from 'beautiful-mermaid'

const svg = await renderMermaid(`
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
`)

example.ts

import { renderMermaidAscii } from 'beautiful-mermaid'

const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)

example.txt

┌───┐     ┌───┐     ┌───┐
│   │     │   │     │   │
│ A │────►│ B │────►│ C │
│   │     │   │     │   │
└───┘     └───┘     └───┘

example.ts

import { renderMermaid, THEMES } from 'beautiful-mermaid'

// Use a built-in theme
const svg = await renderMermaid(diagram, THEMES['tokyo-night'])

// Available themes:
THEMES['zinc-light']
THEMES['zinc-dark']
THEMES['tokyo-night']
THEMES['tokyo-night-storm']
THEMES['tokyo-night-light']
THEMES['catppuccin-mocha']
THEMES['catppuccin-latte']
THEMES['nord']
THEMES['nord-light']
THEMES['dracula']
THEMES['github-light']
THEMES['github-dark']
THEMES['solarized-light']
THEMES['solarized-dark']
THEMES['one-dark']