The Discovery#

Found beautiful-mermaid while browsing for diagram tools. What caught my attention: build-time SVG output with CSS variable theming. No client-side JavaScript, instant theme switching, and the diagrams actually look good.

Why This Matters#

Technical writing often needs diagrams to explain flows, state machines, or system architecture. The standard options either require manual image exports (tedious to update) or client-side rendering (slow, flash of unstyled content). A build-time approach that outputs themeable SVGs hits the sweet spot.

Usage#

Code Fence Syntax (Simplest)#

Write diagrams directly in MDX using code fences:

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

The rehype-mermaid plugin transforms these at build time:

Component Syntax (For More Control)#

When you need frames, captions, or other options, use the Mermaid component:

<Mermaid
  chart={`graph LR
    A --> B --> C`}
  title="Data Flow"
  caption="Optional description"
  frame="simple"
  align="center"
  showCopyButton={true}
/>

Frame Options#

Three frame styles available:

Alignment Options#

Control diagram positioning with the align prop:

• center (default) - centered in container
• left - aligned to start
• right - aligned to end
• full - stretches to fill width

Copy Button#

Each diagram includes a copy button (top-right, visible on hover) with options to:

• Copy Mermaid source code
• Copy SVG code
• Download as SVG
• Download as PNG (2x resolution for retina displays)

Disable with showCopyButton={false} when not needed.

Theming#

Diagrams use CSS variables and automatically adapt to light/dark mode. Toggle the theme to see it in action. The key insight from beautiful-mermaid is using CSS custom properties directly in the SVG output. When you toggle themes, the diagram updates instantly without re-rendering.

Variables used: --color-text, --color-bg, --color-border, --color-accent, --color-text-muted, --color-bg-alt

Supported Diagram Types#

• Flowcharts: graph TD, graph LR, graph BT, graph RL
• Sequence: sequenceDiagram
• State: stateDiagram-v2
• Class: classDiagram
• ER: erDiagram

Full test gallery at /artifacts/mermaid-gallery.