# beautiful-mermaid beautiful-mermaid is a TypeScript library that provides an enhanced renderer for [[Mermaid]] diagrams with beautiful themes and ASCII/Unicode output for terminals. It was built by [Craft](https://craft.do) to power diagrams in Craft Agents. ## Why beautiful-mermaid? The default Mermaid renderer has some limitations: - Aesthetics could be more professional - Complex theming requires wrestling with CSS classes - No terminal/ASCII output for CLI tools - Heavy dependencies for simple diagrams beautiful-mermaid solves these by providing fast, beautiful rendering that works everywhere—from rich UIs to plain terminals. ## Features - **5 diagram types**: Flowcharts, State, Sequence, Class, and ER diagrams - **Dual output**: SVG for rich UIs, ASCII/Unicode for terminals - **15 built-in themes**: Tokyo Night, Catppuccin, Nord, Dracula, GitHub, Solarized, One Dark, and more - **Full Shiki compatibility**: Use any VS Code theme directly - **Live theme switching**: CSS custom properties, no re-render needed - **Mono mode**: Beautiful diagrams from just 2 colors (bg + fg) - **Zero DOM dependencies**: Pure TypeScript, works everywhere - **Ultra-fast**: Renders 100+ diagrams in under 500ms ## Installation ```bash npm install beautiful-mermaid # or bun add beautiful-mermaid ``` ## Usage ### SVG Output ```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 ```typescript import { renderMermaidAscii } from 'beautiful-mermaid' const ascii = renderMermaidAscii(`graph LR; A --> B --> C`) ``` Output: ``` ┌───┐ ┌───┐ ┌───┐ │ A │────►│ B │────►│ C │ └───┘ └───┘ └───┘ ``` ## Theming System The theming is based on a two-color foundation: - **bg**: Background color - **fg**: Foreground color From these two colors, the entire diagram is derived using `color-mix()`. Optional "enrichment" colors can override specific derivations: `line`, `accent`, `muted`, `surface`, `border`. ## Credits The ASCII rendering engine is based on [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff ## Related - [[Mermaid]] ## References - Source code: https://github.com/lukilabs/beautiful-mermaid - Craft: https://craft.do - Craft Agents: https://agents.craft.do