Beautiful‑Mermaid: Ultra‑Fast, Fully‑Themeable Mermaid Diagram Renderer

Beautiful‑Mermaid is a tiny, pure‑TypeScript library that turns Mermaid‑DSL into beautiful SVGs or terminal‑friendly ASCII art with minimal footprint. It’s the engine powering Craft Agents’ diagram support, delivering 100 + diagrams in under 500 ms, 15 ready‑made themes, and seamless CSS‑based live theme switching.

Key Features

• Zero DOM dependencies – Pure TS, works in Node, browser, or a CLI.
• Fast rendering – Ultra‑light bundler, 100 + diagrams in sub‑half‑second.
• Dual output – SVG for rich UIs, ASCII/Unicode for terminals.
• Rich theming – Two‑color mono mode, enriched mode, 15 built‐in themes, Shiki integration.
• Live theme switching – CSS custom properties, no re‑render.
• Multi‑diagram support – Flowcharts, State, Sequence, Class, and ER diagrams.

Getting Started

# Install via your favourite package manager
npm i beautiful-mermaid
# or
bun add beautiful-mermaid
# or
pnpm add beautiful-mermaid

Rendering an SVG

import { renderMermaid } from 'beautiful-mermaid';

const diagram = `
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
`;

const svg = await renderMermaid(diagram, {
  // You can pick a pre‑built theme
  ...THEMES['tokyo-night'],
  // or provide a custom color scheme
  bg: '#1a1b26',
  fg: '#a9b1d6',
});

document.body.innerHTML = svg;

Rendering ASCII for a CLI

import { renderMermaidAscii } from 'beautiful-mermaid';

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

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

Custom Theming with CSS Variables

All theme colors are CSS custom properties on the <svg> root element, enabling instant live switches:

svg.style.setProperty('--bg', '#282a36');
svg.style.setProperty('--fg', '#f8f8f2');

The SVG instantly updates without a re‑render.

Integrating Shiki Themes

If you prefer VS Code‑style themes, simply import a Shiki theme and convert it:

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

const highlighter = await getSingletonHighlighter({
  themes: ['dracula', 'catppuccin-mocha'],
});

const colors = fromShikiTheme(highlighter.getTheme('dracula'));
const svg = await renderMermaid(diagram, colors);

Example: Rendering a Flowchart

const flow = `
flowchart TD
  Start --> Decide{Decision}
  Decide -->|Yes| Process
  Decide -->|No| End
`;

const svg = await renderMermaid(flow, THEMES['one-dark']);

Why Beautiful‑Mermaid?

• Simplicity – No heavy dependencies, pure TS.
• Performance – Benchmark shows 100+ diagrams < 500 ms.
• Versatility – Works in web, Node, or any environment.
• Extensibility – Add your own themes, integrate with Shiki, switch colors live.
• Open‑Source – MIT‑licensed, community‑friendly.

Use Cases

• Developer Tools – Embed interactive flowcharts in VS Code extensions.
• Documentation – Generate SVG diagrams for MkDocs or Docsify.
• CLI Utilities – Print human‑readable diagrams in terminal logs.
• Chatbots – Visualize logic in chat UI when the user requests diagram help.

Community & Contribution

Beautiful‑Mermaid is an active project on GitHub. Contributions are welcome via issues and pull requests. Check out the issues thread for open tasks or the contributing guide.

TL;DR

• Install beautiful-mermaid.
• Call renderMermaid() for SVG or renderMermaidAscii() for text.
• Use built‑in themes or custom colors.
• Switch themes at runtime with CSS variables.
• Leverage Shiki for VS Code theme colours.

With Beautiful‑Mermaid you can turn plain Mermaid text into a stunning visual experience—whether inside a browser, a terminal or anywhere else you need it.