Mermaid Diagram Renderer

On this page

An Astro integration that pre-renders Mermaid diagrams to inline SVG at build time. No client-side JavaScript, because diagrams are static SVG in the output HTML. No heavyweight browser CLI required, either, because this uses svgdom (just a few MBs, a couple of orders of magnitude lighter than Playwright) to render SVGs.

Current version: 0.1.0 --npm

Installation

$ npm install astro-better-mermaid mermaid

Setup

In astro.config.ts:

import mermaidSSR from 'astro-better-mermaid';

export default defineConfig({
  integrations: [
    mermaidSSR({
      theme: 'default',
    }),
  ],
});

Options

Option	Type	Default	Description
`theme`	`string`	`'default'`	Mermaid theme: `default`, `dark`, `neutral`, `forest`
`titleFix`	`boolean`	`true`	Strip title from rendered SVG (prevents duplicate headings)
`injectCSS`	`boolean`	`true`	Auto-inject default styles
`securityLevel`	`string`	`'loose'`	Mermaid `securityLevel` setting

Usage in MDX

Write standard Mermaid fences in your MDX files:

```mermaid
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Do thing]
  B -->|No| D[Don't do thing]
  C --> E[End]
  D --> E
```

Live example

How it works

The integration registers a remark plugin (remarkMermaidSSR) that transforms ```mermaid fences into inline SVG during the Astro build. It uses svgdom to render Mermaid server-side without a headless browser.

To use the remark plugin directly without the integration:

import { remarkMermaidSSR } from 'astro-better-mermaid';

export default defineConfig({
  markdown: {
    remarkPlugins: [[remarkMermaidSSR, { theme: 'neutral' }]],
  },
});