mermaid-js/mermaid

What it does

Mermaid is a JavaScript library and renderer that turns Markdown-inspired text definitions into diagrams, so charts can live in version control alongside the code and documentation they describe. It targets developers and technical writers who want to avoid drag-and-drop design tools and keep diagrams easy to update. The README lists 20+ diagram types, including flowcharts, sequence diagrams, class and state diagrams, ER, Gantt, pie, Git graph, mindmap, timeline and Sankey, with themes and layout options source:53.

Diagrams are written as text, so changes show up as diffs and can be reviewed like code. Example flowcharts and sequence diagrams show the syntax that is rendered in a mermaid code block source:59, and many tools, including GitHub Markdown, render these blocks natively source:46. There is also a live editor for prototyping without a local setup source:43.

Quick start

Try a diagram without installing anything: open the live editor, paste a definition, and inspect the rendered result. A minimal flowchart is:

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

The same definition appears in the README examples source:60. To use it in a project, install the npm package with npm install mermaid (the package is published as mermaid source:5), import and initialize the library in your page, call the render API with a diagram definition and a target element, then insert the returned SVG into the page. The exact API call signatures are in the official usage documentation source:48; this description does not guess the method names. The Getting Started guide covers the first render in more detail source:8.

Usage constraints

Mermaid output is an SVG rendered in the browser, so a JavaScript environment and a DOM target are required. For public sites that display untrusted user content, the documentation recommends the sandboxed iframe security level, which blocks malicious JavaScript but also disables some interactive diagram features; incoming definitions are sanitized, though the project does not guarantee that no bypass exists source:39. Security issues should be reported privately to the listed security address rather than through public issues source:40.

The project is MIT licensed. Its layout and drawing foundations are credited to d3 and dagre-d3, with the sequence diagram grammar derived from another project source:41. The command-line interface and the live editor are separate projects rather than part of this repository source:37.

HotRepo's take

A 2025 Hacker News discussion with 255 points and 107 comments is the strongest visible signal around this repository: commenters described using inline Mermaid blocks in GitHub pull requests and in Notion or Obsidian documents, and one workflow converted hand-drawn pipeline sketches into Mermaid source with a multimodal model, then hand-tuned the result source:44049619. Those are anecdotal uses from 2025, not measurements of project quality. In HotRepo records, the repository appeared on the TypeScript daily list on 2026-11-04 with 23 stars gained that day, which is a single snapshot rather than a trend. With roughly 91k stars and 9.4k forks, it is a long-running project; the practical takeaway is that its text-first, renderer-driven design fits documentation workflows where diagrams must be reviewed and updated alongside code.