mermaid-styling
Mermaid Styling
Mermaid draws each diagram into an SVG at render time, sizing every box by measuring its label text in the configured font. Styling that ignores this shows up as clipped labels, overlapping text, or diagrams that look right on one page load and broken on the next. This skill covers the styling options, the layout engines, the text-measurement traps, and a complete theme. The rendering behavior was verified on Mermaid 11.15–11.17; Mermaid 12 (September 2026) bundles ELK and changes defaults, and the references call out where that matters.
Three ways to style a diagram
| Option | Where it lives | Reaches | Use it for |
|---|---|---|---|
themeVariables |
mermaid.initialize, plugin config, or per-diagram frontmatter |
Colors and the font Mermaid measures with | Palette, font family and size |
themeCSS |
mermaid.initialize, plugin config, or frontmatter (filtered) |
Everything inside the SVG, scoped under the svg's id | Borders, shadows, radius, fill cycling, weights |
| Page CSS | Your site stylesheet | The <svg> element and its container, plus anything without an id-scoped rule |
Canvas background, padding, cursor, layout of the block |
Use theme: 'base' and look: 'classic' as the starting point. On a Markdown host with no stylesheet access, per-diagram frontmatter is the only option, and Mermaid's sanitizer strips more than you expect from it; see references/hosts.md.