Mermaid.js — Complete Ecosystem Guide

Mermaid.js is an open-source JavaScript library (MIT license, 86,800+ GitHub stars as of March 2026) that turns Markdown-inspired text definitions into rendered SVG diagrams. Its core value proposition is diagrams-as-code: version-controllable, diff-friendly, machine-parseable diagram definitions that live alongside source code and documentation.

The library is natively supported in GitHub (Markdown, issues, PRs), GitLab, Notion, Obsidian, Confluence, Docusaurus, MkDocs Material, VS Code, JetBrains IDEs, and dozens of other platforms. The current stable release is v11.13.0 (published to npm ~March 14, 2026), maintained by the mermaid-js organization on GitHub and commercially backed by Mermaid Chart (mermaid.ai).

Diagram-as-Code — The practice of defining diagrams in a text-based DSL (domain-specific language) rather than using graphical editors. Mermaid's DSL is loosely inspired by Markdown syntax, where indentation, arrows, and keywords define nodes, edges, and relationships.

Rendering Pipeline — Mermaid parses text definitions through a Langium-based parser (upgraded to Langium v4 in v11.13.0), builds an internal graph representation, applies a layout algorithm, and renders the result as inline SVG in the browser DOM. Server-side rendering uses Puppeteer (headless Chromium) via the CLI.

Frontmatter Configuration — YAML metadata placed between --- delimiters at the top of a Mermaid definition. This is the primary mechanism for per-diagram configuration of theme, layout engine, look, and engine-specific options.

Directives — The legacy %%{init: {...}}%% syntax for per-diagram configuration. Still functional but frontmatter is preferred for readability and consistency.

Layout Engine — The algorithm that computes node positions and edge routing. Mermaid supports four engines: Dagre (default), ELK, Tidy Tree, and CoSE-Bilkent.

Look — A rendering style applied on top of the layout. Two looks exist: classic (clean-line SVG) and handDrawn (sketch-like, using rough.js). Look is independent of theme and layout.

Theme — A set of color variables that control the visual palette. Five built-in themes exist, with base being the only one that supports full customization via themeVariables.