Mermaid

Mermaid is a JavaScript-based diagramming and charting library that renders complex diagrams from simple, markdown-inspired text definitions instead of drag-and-drop tools. It ships as an importable library with a mermaid.initialize() / mermaid.run() API that scans a page for .mermaid blocks and renders them to SVG in the browser, and it natively powers Mermaid code fences on GitHub, GitLab, and many documentation and note-taking tools.

Because diagrams are plain text, they live alongside code in version control, get reviewed in diffs, and never go stale the way exported images do. The library supports over 20 diagram types (flowcharts, sequence, class, state, ER, Gantt, Git graphs, mindmaps, timelines, and more), pluggable rendering layouts, theming, and a sandboxed/sanitized rendering mode for embedding user-authored diagrams safely.

What You Get

• A single mermaid npm package exposing initialize(), run(), and render() APIs for parsing and rendering diagram text to SVG in the browser or a headless DOM
• 20+ built-in diagram types (flowchart, sequence, class, state, ER, Gantt, pie, Git graph, mindmap, timeline, sankey, C4, requirement, quadrant, packet, and more)
• Pluggable layout engines, including the default dagre-based layout and optional ELK and tidy-tree layout packages
• Built-in sanitization via DOMPurify plus a sandboxed iframe rendering mode for safely embedding untrusted diagram text
• Theming support (default, dark, forest, neutral, base) with per-diagram style configuration
• Native rendering support already wired into GitHub, GitLab, Notion, and dozens of other markdown-aware tools that recognize ```mermaid code fences

Common Use Cases

• Embedding architecture and flow diagrams directly in README files and technical documentation so they render on GitHub without external image tooling
• Generating sequence and state diagrams from text inside internal wikis, static site generators, or documentation-as-code pipelines
• Building an in-app diagram editor or live preview feature (as the Mermaid Live Editor does) using the mermaid library’s parse/render API
• Visualizing Git branching history, Gantt project timelines, or entity-relationship schemas as part of automated reporting or CI-generated docs

Under The Hood

Architecture - Mermaid’s public entry point (src/mermaid.ts) wraps an internal mermaidAPI that drives a pipeline of detect → parse → render. detectType() (in diagram-api/detectType.ts) inspects the leading tokens of the input text to pick a diagram type, Diagram.fromText() lazily loads that diagram’s registered definition via loadDiagram.ts/diagram-orchestration.ts if it isn’t already registered, then hands the text to a per-diagram-type parser (Jison-generated grammars for legacy diagrams, or the newer Langium-based @mermaid-js/parser package for others) which populates a diagram-specific in-memory database (e.g. flowDb.ts). The populated db is passed to rendering-util/render.ts, which delegates to pluggable layout algorithms (the default dagre-based layout, plus optional ELK and tidy-tree packages) to compute positions before painting SVG via D3. Each of the 20+ diagram types under src/diagrams/* is a self-contained module (parser + db + renderer + styles), registered through a common DiagramDefinition interface, which is what lets new diagram types be added without touching the core orchestration code.

Tech Stack - The library is TypeScript-first, built with Vite/Rollup, and its runtime dependencies reveal a layered rendering stack: D3 (d3, d3-sankey) for SVG manipulation and data-driven layout, dagre-d3-es for default graph layout, cytoscape plus cytoscape-cose-bilkent/cytoscape-fcose for force-directed diagrams, roughjs for the hand-drawn sketch theme, katex for math rendering inside diagrams, dompurify and @braintree/sanitize-url for output sanitization, marked for markdown-in-labels support, and the sibling @mermaid-js/parser package for Langium-based grammars. It’s organized as a pnpm workspace monorepo (packages/mermaid, packages/parser, packages/mermaid-layout-elk, etc.), so the core library composes cleanly with optional layout and parser plugins that ship as separate npm packages.

Code Quality - The mermaid package has extensive automated test coverage: 149+ .spec.ts/.spec.js files sit alongside their implementation files (e.g. mermaidAPI.spec.ts, config.spec.ts, flowDb.spec.ts), plus a separate Cypress suite (cypress/) for visual/integration testing and Applitools/Argos-powered visual regression testing in CI. TypeScript strict typing, ESLint, and Prettier are enforced repo-wide, and error handling is explicit — Diagram.fromText() throws a typed UnknownDiagramError for unrecognized diagram types rather than failing silently, and the public run() API exposes a suppressErrors option so consumers can opt into graceful degradation instead of having it forced on them.

API Design - The public surface is deliberately small: mermaid.initialize(config) to configure once, mermaid.run() to auto-render all .mermaid elements on a page, and lower-level mermaid.parse()/mermaid.render() for programmatic use in custom editors or SSR pipelines. Getting started requires no build step beyond import mermaid from 'mermaid' (or a CDN script tag) and a text string — there’s no scaffolding, no required project structure, and sensible defaults handle theme and layout selection automatically, which is a large part of why it has been adopted natively by GitHub, GitLab, and dozens of other markdown-aware tools.