Mermaid

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

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.

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.

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