Mermaid

Mermaid is a text-based diagramming language. diagramkit renders Mermaid files using headless Chromium with the official mermaid library.

Do it with an agent

Author a Mermaid diagram for [TOPIC]. Load the diagramkit-mermaid skill from node_modules/diagramkit/skills/diagramkit-mermaid/ (or its references/) for type-specific guidance. Create <name>.mermaid, render with npx diagramkit render <name>.mermaid, then validate with npx diagramkit validate .diagramkit/ --recursive. Iterate until errors are zero.

Do it manually

Walk the page top-down — file extensions, capabilities, examples, theming, and troubleshooting are each in their own section below.

File Extensions

.mermaid, .mmd, .mmdc — all treated identically.

Capability Matrix

Supported Diagram Types

All mermaid diagram types are supported, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, gantt charts, pie charts, git graphs, mindmaps, and timelines.

Quick Start

Create architecture.mermaid:

1graph TD2    A[Client] -->|HTTP| B[API Gateway]3    B --> C[Auth Service]4    B --> D[Content Service]5    D --> E[(Database)]67    subgraph Backend8        C9        D10        E11    end

Render:

1diagramkit render architecture.mermaid

Output:

1.diagramkit/2  architecture-light.svg3  architecture-dark.svg4  manifest.json

Using with AI Agents

Tell your AI coding agent:

Render all mermaid files in this project to SVG

Or for more control:

Render docs/architecture.mermaid to PNG and SVG with dark mode only

Dark Mode

Mermaid gets two separate renders:

1. Light — mermaid default theme
2. Dark — mermaid base theme with custom dark variables

The dark render is then post-processed with WCAG contrast optimization to fix fill colors that are too bright against dark backgrounds.

Default Dark Theme

The built-in dark palette uses neutral grays with good contrast:

1{2  background: '#111111',3  primaryColor: '#2d2d2d',4  primaryTextColor: '#e5e5e5',5  primaryBorderColor: '#555555',6  lineColor: '#cccccc',7  textColor: '#e5e5e5',8  mainBkg: '#2d2d2d',9  nodeBkg: '#2d2d2d',10  nodeBorder: '#555555',11  clusterBkg: '#1e1e1e',12  // ... additional variables13}

Custom Dark Theme (API)

Override dark theme variables programmatically:

1import { render } from 'diagramkit'23const result = await render(source, 'mermaid', {4  mermaidDarkTheme: {5    background: '#1a1a2e',6    primaryColor: '#16213e',7    primaryTextColor: '#e5e5e5',8    lineColor: '#e5e5e5',9  },10})

Disable Contrast Optimization

1diagramkit render . --no-contrast

1const result = await render(source, 'mermaid', { contrastOptimize: false })

How It Works

Mermaid rendering uses two persistent browser pages in the pool:

• Light page — mermaid.initialize({ theme: 'default' })
• Dark page — mermaid.initialize({ theme: 'base', themeVariables: {...} })

Two pages are needed because mermaid.initialize() is global and cannot be reconfigured per-call. Both pages are reused across renders.

Aspect-ratio rebalance

Mermaid’s default Dagre layout has no aspect-ratio knob, so a flowchart LR with many sequential nodes can render at extreme ratios like 12:1 — fine in a wide browser, hard to read when embedded at 650 px or in mobile docs. diagramkit can detect this and either warn or transparently re-render to a more readable shape.

The behaviour is controlled by mermaidLayout in diagramkit.config.json5 (or per-call via RenderOptions.mermaidLayout). By default the renderer warns when a diagram falls outside a [1:1.9, 3.3:1] band; opting into mode: 'auto' makes it actively try a flipped direction and (if available) the ELK layout engine, then keep whichever variant lands closest to the target ratio.

1{2  mermaidLayout: {3    mode: 'auto',           // 'off' | 'warn' | 'flip' | 'elk' | 'auto'4    targetAspectRatio: 4 / 3,5    tolerance: 2.5,6  },7}

Eligibility: only flowchart / graph diagrams are rebalanced. Sequence, gantt, journey, state, class, ER, pie, mindmap, sankey, gitGraph, and similar diagrams are inherently directional/temporal and degrade to warn-only behaviour. If the source already declares layout or flowchart.defaultRenderer in an %%{init}%% block, the ELK injection is skipped — author intent always wins.

For full schema and validation rules see the Configuration Reference.

Gotchas

• Large diagrams — Mermaid rendering happens in a headless browser page. Diagrams with hundreds of nodes may be slow or exceed Chromium’s rendering budget. Split large diagrams into multiple files.
• Custom CSS in mermaid — diagramkit uses securityLevel: 'strict', so custom CSS or JavaScript in mermaid directives is blocked.
• mermaid.initialize() is global — diagramkit uses separate browser pages for light and dark themes because the initialization is not per-call. Custom theme variables only apply to the dark page via the API’s mermaidDarkTheme option.
• The contrast optimizer may shift colors — fills with high luminance (above 0.4 relative luminance) are darkened to lightness 0.25 while preserving hue. Bright yellows, cyans, and whites are most affected.
• ELK layouts need an extra plugin — the mermaidLayout: 'elk' | 'auto' modes inject an ELK directive but mermaid v11 doesn’t ship the layout engine by default. Install @mermaid-js/layout-elk if you need ELK to actually run; otherwise auto falls back to flip-only.

Tips

1. Use semantic node IDs — A[Web Server] not A[Node 1]
2. Keep diagrams focused — aim for 15 or fewer nodes; split complex systems into multiple files
3. Use subgraphs for logical grouping
4. Prefer neutral fill colors — the dark mode post-processor adjusts high-luminance fills automatically
5. Avoid bright neon colors — they may not pass dark mode contrast checks