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.
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 | Show title="..." from the code fence meta as a caption below the diagram |
injectCSS | boolean | true | Auto-inject default styles |
securityLevel | string | 'loose' | Mermaid securityLevel setting |
cache | boolean | true | Cache rendered diagrams on disk between builds |
cacheDir | string | 'node_modules/.cache/astro-better-mermaid' | Where cached diagrams live, relative to the working directory |
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' }]],
},
});
Caching
Rendering a diagram is the slow part, so the plugin caches each rendered diagram on disk and reuses it on later builds. Entries are keyed by the Mermaid version, the theme and security level, and the diagram source, so editing a diagram or upgrading Mermaid renders it again, as does upgrading to a release of this package that changes how diagrams render. Diagrams that fail to render are never cached.
Each diagram’s SVG id comes from its position on the page and a hash of its source, so the same page builds to the same HTML every time. Earlier versions used a random id.
Set cache: false to turn the disk cache off, or point cacheDir somewhere that persists between CI runs to share it.
Upgrading to 0.3.0
Labels now fit their shapes: multi-line labels get room for every line, and text is centered in cylinders and other shapes and on edge label backgrounds. Rendering changed, so cached diagrams render again after you upgrade.
If you set injectCSS: false and copied the stylesheet into your own CSS, update your copy:
- Remove
transform: translateY(16px) !important;from the.edgeLabel rectrules in both themes. It made up for the old edge label measurement and now pushes label backgrounds below their text. - Color
.loopTextand.sectionTitlelike body text in both themes, soalt,loop, andelseconditions in sequence diagrams stay readable. The light theme used to color.loopTextalmost white.
Use with Sätteri
When markdown.processor is a Sätteri processor, the integration adds its Sätteri plugins to that processor instead of registering remark plugins. Nothing else in the setup changes:
import mdx from '@astrojs/mdx';
import { satteri } from '@astrojs/markdown-satteri';
import mermaidSSR from 'astro-better-mermaid';
const processor = satteri();
export default defineConfig({
markdown: { processor },
integrations: [mdx({ processor }), mermaidSSR({ theme: 'neutral' })],
});
Pass the same processor to mdx(), as above, so MDX files get the plugins too.
To wire the plugins yourself, import them from astro-better-mermaid/satteri. They take the same options as the remark plugins:
import { mermaidTitle, mermaidSSR } from 'astro-better-mermaid/satteri';
const processor = satteri({
// mermaidTitle first, as with mermaidTitleFix and remarkMermaidSSR
mdastPlugins: [mermaidTitle(), mermaidSSR({ theme: 'neutral' })],
});
Without the integration, keep svgdom and mermaid in vite.ssr.external and import astro-better-mermaid/styles.css in your layout, as the integration would.