Mermaid Administrator & Developer Guide

1. Architecture Overview

Mermaid is a JavaScript-based diagramming and charting library that renders Markdown-inspired text definitions into SVG diagrams in the browser. It is distributed as an npm package (mermaid v11.14.0), operates entirely client-side, and exposes no server-side components, CLI commands, or API endpoints.

1.1 Monorepo Structure

The codebase is organized as a pnpm monorepo (root name mermaid-monorepo v10.2.4) containing eight packages:

1.2 Core Rendering Pipeline

Every diagram flows through the same pipeline:

Text Input
  → detectType()           # regex-based diagram type detection
  → getDiagramLoader()     # lazy-load diagram module if not registered
  → Parser                 # jison (legacy) or langium (modern)
  → Diagram DB             # in-memory data store populated by parser
  → Renderer               # SVG generation using d3 + layout algorithm
  → SVG Output             # sanitized via DOMPurify

The pipeline is orchestrated by Diagram.fromText() (static factory in packages/mermaid/src/Diagram.ts), which detects the diagram type, loads the appropriate parser/db/renderer triplet, runs the parser, and returns a Diagram instance ready for rendering.

1.3 Key Source Modules

1.4 Diagram Type Architecture

Each of the 27 built-in diagram types follows a consistent module pattern within packages/mermaid/src/diagrams/{type}/:

Note

Older diagram types (flowchart, sequence, gantt, class, state, ER, pie, C4, requirement, user-journey, git graph) use jison parsers (.jison grammar files compiled to JavaScript). Newer types (packet, info, pie v2, gitGraph v2, radar, architecture, wardley, treemap, treeView, eventmodeling, venn) use Langium grammars (.langium files) via the @mermaid-js/parser package.

1.5 Supported Diagram Types (27)

flowchart, sequence, class, state, er, gantt, pie, mindmap, timeline, quadrant-chart, xychart, requirement, c4, sankey, packet, block, git graph, user-journey, architecture, ishikawa, kanban, radar, venn, treemap, tree-view, eventmodeling, wardley

2. System Requirements

2.1 Development Environment

2.2 Runtime Dependencies (Core Package)

2.3 Runtime Dependencies (Satellite Packages)

2.4 Browser Requirements

Mermaid targets modern browsers with ES module support. The esbuild configuration targets the modules build output. No polyfills are included; consumers must provide them if targeting older browsers.

Important

Mermaid is a browser-side library only. It requires a DOM environment. Server-side rendering requires a DOM shim (e.g., jsdom) or a headless browser. The library auto-registers a window.addEventListener('load', ...) listener when document is defined.

3. Configuration Reference

Mermaid uses a three-tier configuration architecture:

1. defaultConfig -- Immutable baseline loaded from config.schema.yaml via a custom Vite plugin, frozen with Object.freeze().
2. siteConfig -- Set via mermaid.initialize(config). Merges onto defaultConfig. Persists across reset() calls. This is where site-wide defaults belong.
3. currentConfig -- Active config during rendering. Starts as a copy of siteConfig, then has directives applied on top. Reset between diagrams via reset().

defaultConfig (frozen)
    └──► siteConfig (via initialize)
            └──► currentConfig (via directives)

3.1 Config API Functions

Warning

The secure array in config prevents certain keys from being overridden via directives. By default, securityLevel, maxTextSize, and other sensitive keys are in this array. Attempting to set a secure key via a %%{init: {...}}%% directive will silently fail with a debug log message.

3.2 Global Configuration (MermaidConfig)

3.3 ELK Layout Configuration (elk)

3.4 Flowchart Configuration (flowchart: FlowchartDiagramConfig)

3.5 Sequence Diagram Configuration (sequence: SequenceDiagramConfig)

3.6 Gantt Diagram Configuration (gantt: GanttDiagramConfig)

3.7 Class Diagram Configuration (class: ClassDiagramConfig)

3.8 State Diagram Configuration (state: StateDiagramConfig)

3.9 ER Diagram Configuration (er: ErDiagramConfig)

3.10 Pie Diagram Configuration (pie: PieDiagramConfig)

3.11 Quadrant Chart Configuration (quadrantChart: QuadrantChartConfig)

3.12 XY Chart Configuration (xyChart: XYChartConfig)

XY Chart Axis (xAxis/yAxis: XYChartAxisConfig):

3.13 Journey Diagram Configuration (journey: JourneyDiagramConfig)

3.14 Timeline Diagram Configuration (timeline: TimelineDiagramConfig)

Shares the same structure as JourneyDiagramConfig with these additions:

3.15 Git Graph Configuration (gitGraph: GitGraphDiagramConfig)

3.16 C4 Diagram Configuration (c4: C4DiagramConfig)

The C4 diagram configuration contains extensive font and color settings for every C4 element type (Person, System, Container, Component -- each with regular and external variants, plus DB and Queue subtypes). Key structural settings:

Each element type has *FontSize, *FontFamily, *FontWeight, *_bg_color, *_border_color, and *Font (calculator function) settings. The naming pattern follows: {element}FontSize, external_{element}FontSize, etc.

3.17 Sankey Diagram Configuration (sankey: SankeyDiagramConfig)

3.18 Packet Diagram Configuration (packet: PacketDiagramConfig)

3.19 Other Diagram Configurations

3.20 Base Diagram Config (BaseDiagramConfig)

All per-diagram configs extend BaseDiagramConfig:

4. Deployment & Scaling

4.1 Installation Methods

npm/pnpm/yarn:

npm install mermaid
# or
pnpm add mermaid
# or
yarn add mermaid

CDN (ESM):

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

4.2 Build Outputs

The esbuild pipeline (.esbuild/build.ts) produces multiple distribution formats in packages/mermaid/dist/:

4.3 Integration Patterns

Auto-rendering (simplest):

<div class="mermaid">
  graph TD;
    A-->B;
</div>
<script type="module">
  import mermaid from '/path/to/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

Programmatic rendering:

import mermaid from 'mermaid';

mermaid.initialize({ startOnLoad: false, theme: 'dark' });

const { svg, bindFunctions } = await mermaid.render('diagram-id', 'graph TD; A-->B');
document.getElementById('output').innerHTML = svg;
if (bindFunctions) {
  bindFunctions(document.getElementById('output'));
}

Targeted node rendering:

await mermaid.run({
  nodes: [document.getElementById('my-diagram')],
  suppressErrors: true,
  postRenderCallback: (id) => console.log(`Rendered: ${id}`),
});

Tip

When calling mermaid.render() or mermaid.parse() concurrently, Mermaid uses an internal execution queue to serialize calls. Each call is enqueued and processed sequentially, preventing race conditions in the shared diagram registry and config state.

4.4 Registering External Diagrams

Third-party diagram types integrate through the ExternalDiagramDefinition interface:

await mermaid.registerExternalDiagrams([
  {
    id: 'custom-diagram',
    detector: (text) => text.startsWith('custom'),
    loader: () => import('./custom-diagram.js'),
  },
], { lazyLoad: true });  // lazyLoad: false loads immediately

The mermaid-example-diagram package serves as the reference implementation for building external diagram plugins.

4.5 Registering Layout Algorithms

Custom layout engines register through registerLayoutLoaders:

import { registerLayoutLoaders } from 'mermaid';

registerLayoutLoaders([
  {
    name: 'custom-layout',
    loader: () => import('./custom-layout.js'),
  },
]);

4.6 Docker-Based Development

The repository includes Docker support for the documentation site (packages/mermaid/src/docs/). The docs dev server can run inside Docker using pnpm dev:docker which binds to all interfaces (host 0.0.0.0) on port 3333.

5. Operations

5.1 Build Commands

5.2 Testing Commands

5.3 Lint Commands

5.4 Release Commands

5.5 Log Levels

The logger (packages/mermaid/src/logger.ts) supports six levels:

Set via logLevel config key or numerically. Default is fatal (5) -- only fatal errors appear in the console. Each log message is prefixed with a timestamp (ss.SSS format) and level name.

5.6 Error Handling

Mermaid defines two custom error classes:

• UnknownDiagramError -- Thrown when no detector matches the input text. Message: "No diagram type detected matching given configuration for text: {text}".
• MermaidParseError -- Thrown by the Langium parser for syntax errors. Message: "Unknown diagram type: {diagramType}".

When suppressErrorRendering is false (default), parse errors cause a "Syntax error" diagram to be rendered in place of the failed diagram. Set suppressErrorRendering: true to prevent this behavior.

The setParseErrorHandler(fn) method provides a global error callback:

mermaid.setParseErrorHandler((err, hash) => {
  console.error('Mermaid parse error:', err);
});

6. Performance

6.1 Text Size Limits

The maxTextSize configuration (default: 50,000 characters) limits the input text length. The maxEdges configuration (default: 500) caps the number of edges in a single diagram. Both prevent denial-of-service through excessively large diagrams.

6.2 Layout Algorithm Selection

Tip

For large flowcharts (100+ nodes), switching from dagre to ELK layout often produces better results. Set layout: 'elk' in the config or via directive: %%{init: {"layout": "elk"}}%%.

6.3 Lazy Loading

Diagram type modules are lazy-loaded by default. The registerExternalDiagrams function accepts a lazyLoad option (default: true). When lazy-loading is enabled, diagram code is only fetched when a matching diagram definition is first encountered.

6.4 Deterministic Rendering

For stable diffs in version-controlled SVG output, enable deterministicIds: true with an optional deterministicIDSeed string. This replaces random UUIDs with sequential, reproducible identifiers using the InitIDGenerator class.

6.5 Bundle Size Optimization

The @mermaid-js/tiny package (v11.14.0) provides a minimal build variant that excludes less-common diagram types. For applications needing only specific diagrams, tree-shaking with the tiny build significantly reduces bundle size.

7. Security

7.1 Security Levels

Mermaid provides four security levels, controlled by securityLevel:

Caution

Setting securityLevel: 'loose' allows HTML rendering in diagram labels. Only use this in environments where you fully control the diagram input. User-submitted diagrams with loose security can execute XSS attacks despite DOMPurify sanitization.

7.2 HTML Sanitization

All rendered HTML/SVG passes through DOMPurify (dompurify ^3.3.1). The dompurifyConfig option allows passing custom DOMPurify configuration if the defaults are too restrictive or not restrictive enough.

7.3 URL Sanitization

URLs in diagrams (links, click handlers) are sanitized via @braintree/sanitize-url, which blocks javascript:, vbscript:, and data: protocol URLs.

7.4 Config Sanitization (Directive Protection)

The sanitize() function in config.ts provides three layers of protection against malicious directives (%%{init: {...}}%%):

1. Secure key enforcement -- Keys in the secure array cannot be overridden by directives. By default: secure, securityLevel, startOnLoad, maxTextSize, maxEdges.

2. Prototype pollution protection -- Any key starting with __ (double underscore) is silently deleted.

3. XSS injection prevention -- String values containing <, >, or url(data: are deleted. This prevents SVG/HTML injection via directive values.

// Example: these directive values would be stripped
%%{init: {
  "fontFamily": "<script>alert('xss')</script>",  // stripped (contains <)
  "__proto__": {"polluted": true},                  // stripped (__ prefix)
  "securityLevel": "loose"                          // stripped (secure key)
}}%%

7.5 Additional Directive Sanitization

The sanitizeDirective() function (packages/mermaid/src/utils/sanitizeDirective.ts) provides a secondary sanitization pass for directives before they enter the config system, adding depth-limited traversal to prevent deeply nested attack payloads.

7.6 XSS Test Suite

The project maintains dedicated XSS tests:

• cypress/integration/other/xss.spec.js -- End-to-end XSS regression tests
• cypress/platform/xss*.html -- XSS test fixtures for manual and automated testing

Important

When integrating Mermaid into a CMS or user-facing application, always use securityLevel: 'strict' (the default) and ensure maxTextSize is set to a reasonable limit. Add the secure array to your initialize() call to lock down any additional config keys that users should not be able to override.

7.7 Content Security Policy (CSP)

When using securityLevel: 'sandbox', Mermaid creates an <iframe> with the sandbox attribute. For strict CSP environments:

• style-src 'unsafe-inline' is required because Mermaid generates inline <style> elements for themes.
• script-src must allow the Mermaid library source.
• If using htmlLabels: true, <foreignObject> elements are inserted into SVG, which some CSP configurations may block.

8. Developer Internals

8.1 Diagram Plugin Architecture

To create a new diagram type, implement these four components:

// 1. Detector: regex that identifies your diagram type
export const detector = (text: string, config?: MermaidConfig): boolean => {
  return /^\s*myDiagram/.test(text);
};

// 2. Database: parse state management
export const db = {
  clear: () => { /* reset state */ },
  setDiagramTitle: (title: string) => { /* store title */ },
  getDiagramTitle: () => string,
  // ... domain-specific getters/setters
};

// 3. Renderer: SVG generation
export const renderer = {
  draw: async (text: string, id: string, version: string, diagram: Diagram) => {
    // Use d3 to create SVG elements
  },
};

// 4. Styles: CSS generator
export const styles = (options: any): string => {
  return `.node { fill: ${options.primaryColor}; }`;
};

// Bundle as DiagramDefinition
export const diagram: DiagramDefinition = { db, parser, renderer, styles };

Register with the detection system:

import { addDetector } from 'mermaid/diagram-api/detectType';

addDetector('myDiagram', detector, () =>
  import('./myDiagram').then(m => ({ id: 'myDiagram', diagram: m.diagram }))
);

8.2 Parser Architecture

Jison parsers (legacy):

Located in packages/mermaid/src/diagrams/{type}/parser/*.jison. These are Bison/Yacc-style grammars compiled to JavaScript at build time. The compiled parser attaches to parser.parser.yy which is set to the diagram's DB for direct state mutation during parsing.

Langium parsers (modern):

Located in packages/parser/src/language/{type}/. These use Langium's grammar language (.langium files) for type-safe AST generation. The @mermaid-js/parser package exports parser services for each diagram type. Langium parsers produce a typed AST rather than mutating a DB directly, then a transformer maps the AST to the DB format.

Current Langium-based diagrams: packet, info, pie (v2), gitGraph (v2), radar, architecture, wardley, treemap, treeView, eventmodeling, venn.

The common infrastructure shared between Langium parsers lives in packages/parser/src/language/common/:

• CommonTokenBuilder (extends AbstractMermaidTokenBuilder) -- Shared tokenization logic
• CommonValueConverter (extends AbstractMermaidValueConverter) -- Shared value conversion

8.3 Theme System

Mermaid ships 11 themes, implemented in packages/mermaid/src/themes/:

Each theme module exports a getThemeVariables(userOverrides?) function that returns a complete set of CSS variables. The base theme is specifically designed as a customization foundation -- set theme: 'base' and provide themeVariables to create a fully custom look:

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#BB2528',
    primaryTextColor: '#fff',
    primaryBorderColor: '#7C0000',
    lineColor: '#F8B229',
    secondaryColor: '#006100',
    tertiaryColor: '#fff',
  },
});

Theme variables flow through the pipeline: initialize() passes themeVariables to the theme's getThemeVariables(), which computes derived colors (using the khroma library for color manipulation). The computed variables then feed into each diagram's styles() function to generate scoped CSS.

Note

The 'null' theme value (string "null") disables theming entirely. This is useful when you provide all styling via external CSS.

8.4 Layout System

The rendering pipeline supports pluggable layout algorithms through LayoutLoaderDefinition:

Dagre (default): The dagre layout engine (dagre-d3-es) operates in two paths:

• Legacy dagre-wrapper (packages/mermaid/src/dagre-wrapper/) -- A recursive rendering implementation that handles subgraphs/clusters by recursively calling itself for nested graphs. This is the default for flowcharts, class diagrams, and state diagrams.
• Unified layout path (packages/mermaid/src/rendering-util/layout-algorithms/dagre/) -- A newer integration point used by the layout algorithm abstraction.

The dagre-wrapper's recursiveRender() function is notable: it inserts nodes into the DOM to measure their dimensions, then runs dagre layout on the abstract graph, and finally positions the DOM elements. For cluster nodes, it calls itself recursively.

ELK (@mermaid-js/layout-elk): The ELK (Eclipse Layout Kernel) integration wraps elkjs for higher-quality layouts. It provides fine-grained control through the elk config namespace (node placement strategy, cycle breaking, model order preservation).

CoSE-Bilkent (packages/mermaid/src/rendering-util/layout-algorithms/cose-bilkent/): A force-directed layout using the Cytoscape.js ecosystem. Produces organic, spring-like layouts.

Tidy Tree (@mermaid-js/layout-tidy-tree): A bidirectional tree layout algorithm optimized for mindmaps and hierarchical data. Supports both top-down and left-right orientations.

8.5 Rendering Utilities

The packages/mermaid/src/rendering-util/ directory contains shared rendering infrastructure:

• rendering-elements/ -- Shape rendering functions for 50+ node shapes (rectangles, diamonds, circles, hexagons, stadiums, cylinders, etc.), edge rendering, cluster rendering, and marker insertion.
• layout-algorithms/ -- Layout algorithm implementations and abstractions.
• render.ts -- Core render function and layout loader registry.
• icons.ts -- Icon pack registration system (sync and async loaders for custom icon sets).

8.6 Accessibility

Mermaid includes built-in accessibility support (packages/mermaid/src/accessibility.ts):

• SVG elements receive role="graphics-document document" (with ARIA 1.0 fallback).
• aria-roledescription is set to the diagram type name.
• accTitle and accDescription frontmatter directives generate <title> and <desc> elements with proper aria-labelledby/aria-describedby linkage.

8.7 Entity Encoding

Mermaid uses a custom entity encoding scheme to safely pass special characters through parsers. The encodeEntities() function in utils.ts converts HTML entities (e.g., #9829; for a heart) into an internal escape format (fl°°9829¶ß), which survives parser transformations and is decoded back during rendering.

8.8 Testing Strategy

Unit Tests (vitest):

Located alongside source files as *.spec.ts and in packages/parser/tests/. Run with pnpm test or pnpm ci. Coverage via @vitest/coverage-v8.

Key test patterns:

• Config tests validate the three-tier config system, secure key enforcement, and directive handling.
• Diagram tests verify parser output and DB state for each diagram type.
• Accessibility tests use jsdom to verify SVG attributes.

End-to-End Tests (Cypress):

Located in cypress/integration/. Structure:

• cypress/integration/rendering/ -- Visual regression tests for each diagram type.
• cypress/integration/other/ -- XSS security tests, configuration tests.
• cypress/platform/ -- HTML test fixtures including XSS regression pages.
• cypress/helpers/ -- Shared test utilities.
• cypress/support/ -- Cypress custom commands and setup.

Visual regression uses cypress-image-snapshot and Argos CI (@argos-ci/cypress) for screenshot comparison.

Tip

The project uses start-server-and-test to coordinate dev server startup with Cypress test execution. Run pnpm e2e for the full flow, or pnpm cypress:open for interactive test development.

8.9 Contributing: Development Workflow

1. Clone and install:

   git clone https://github.com/mermaid-js/mermaid.git
   cd mermaid
   pnpm install
   

2. Start dev server:

   pnpm dev
   

3. Make changes in packages/mermaid/src/ or other packages.

4. Run tests:

   pnpm test          # lint + unit tests
   pnpm e2e           # end-to-end tests
   

5. Lint and format:

   pnpm lint:fix       # auto-fix eslint + prettier
   

6. Build for production:

   pnpm build
   

Pre-commit hooks (managed by husky + lint-staged) automatically run linting on staged files.

8.10 State Management

The ImperativeState class (packages/mermaid/src/utils/imperativeState.ts) provides a pattern for diagram DB state that can be cleanly reset between renders. Each diagram DB uses this to maintain parse state (nodes, edges, actors, tasks, etc.) with a guaranteed-clean clear() method.

8.11 Interaction System

The interactionDb.ts module manages click handlers for interactive diagrams. Functions registered via addFunction() are executed by attachFunctions() after SVG insertion. In strict security level, click interactions are disabled.

8.12 Internal Helpers (Deprecated)

The internalHelpers export (packages/mermaid/src/internals.ts) exposes internal rendering functions for external diagram plugins. These are explicitly marked as deprecated and may change without notice:

export const internalHelpers = {
  common, getConfig, insertCluster, insertEdge,
  insertEdgeLabel, insertMarkers, insertNode,
  interpolateToCurve, labelHelper, log, positionEdgeLabel,
};

Caution

External diagram plugins currently depend on internalHelpers for rendering primitives. This coupling is a known technical debt. The mermaid team plans to provide a stable rendering API in a future version.

9. Integration Points

9.1 Public API Summary

The mermaid default export provides these methods:

RunOptions:

interface RunOptions {
  querySelector?: string;  // Default: ".mermaid"
  nodes?: ArrayLike<HTMLElement>;  // Overrides querySelector
  postRenderCallback?: (id: string) => unknown;
  suppressErrors?: boolean;  // Default: false
}

ParseOptions and ParseResult:

interface ParseOptions {
  suppressErrors?: boolean;
}

interface ParseResult {
  diagramType: string;
}

RenderResult:

interface RenderResult {
  svg: string;
  bindFunctions?: (element: Element) => void;
}

9.2 Frontmatter and Directives

Mermaid diagrams support YAML frontmatter and inline directives for per-diagram configuration:

Frontmatter:

---
title: My Diagram
config:
  theme: dark
---
flowchart LR
  A --> B

Inline directive:

%%{init: {"theme": "forest", "flowchart": {"nodeSpacing": 100}}}%%
flowchart LR
  A --> B

The utils.detectInit(text) function extracts frontmatter and directive configurations, which are applied as directives to the current config.

9.3 Icon Packs

Custom icons can be registered for use in architecture diagrams and other icon-supporting diagram types:

// Synchronous loader
mermaid.registerIconPacks([
  {
    name: 'my-icons',
    loader: () => ({
      prefix: 'mi',
      icons: { server: { body: '<path d="..."/>', width: 24, height: 24 } },
    }),
  },
]);

// Asynchronous loader
mermaid.registerIconPacks([
  {
    name: 'remote-icons',
    loader: () => fetch('/icons.json').then(r => r.json()),
  },
]);

9.4 Webpack Integration

The tests/webpack/ directory provides a reference implementation for Webpack-based projects, demonstrating how to configure Webpack to bundle Mermaid correctly with its ESM dependencies.

9.5 VitePress Documentation Integration

The official documentation site (packages/mermaid/src/docs/) uses VitePress with:

• unplugin-vue-components for auto-importing Vue components
• unocss for utility-first CSS
• vitepress-plugin-search for full-text search
• A custom IncludesPlugin for file inclusion directives
• A virtual module (virtual:mermaid-config) providing default Mermaid config for live examples

The docs dev server configuration aliases mermaid to the built distribution file (../../dist/mermaid.esm.min.mjs), ensuring docs render with the current build.

9.6 Known Issues

Warning

The flowchart.htmlLabels config is deprecated. Use the root-level htmlLabels setting instead. The root-level value always takes precedence. A deprecation warning is logged on first use of the flowchart-specific setting.