# Mermaid: Generate Diagrams from Text, Rendered in the Browser > Mermaid is a JavaScript library that converts Markdown-like text definitions into flowcharts, sequence diagrams, class diagrams, Gantt charts, and git graphs. It targets developers who need documentation diagrams that can live in version control alongside the code they describe. **mermaid-js/mermaid** — Generation of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown. - Repository: https://github.com/mermaid-js/mermaid - Website: https://mermaid.ai/open-source/ - Stars: 90,420 · Forks: 9,302 - Language: TypeScript - License: MIT - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/mermaid-js-mermaid ## The Doc-Rot Problem Mermaid Targets Diagrams in engineering documentation have a short useful life when stored as image files. Once the code changes, someone must open an external drawing tool, update the diagram, export a new image, and replace the old file. That four-step process is skipped more often than it is done, leaving diagrams that describe a system from three quarters ago. Mermaid attacks this by storing the diagram as text inside the same file as the prose. Because the definition is text, it goes into a pull request, gets reviewed like code, and changes when the code changes. The project's intended audience is developers writing technical documentation. It also targets technical writers who work close to code and want their diagrams to follow the same review process as the documents they accompany. The README states the main purpose as helping "documentation catch up with development." Non-programmers can also produce diagrams through the browser-based Live Editor without installing anything. ## Text Syntax and Diagram Types Mermaid uses a compact, indentation-light syntax that is closer to Markdown than to XML or JSON. Each diagram starts with a keyword that declares its type, followed by node and edge definitions on separate lines. The package.json lists the supported diagram keywords: flowchart, sequence diagram, class diagram, Gantt chart, and git graph. The full documentation at mermaid.ai describes additional types including state diagrams, entity-relationship diagrams, user journey maps, and pie charts. The renderer is written in TypeScript and runs entirely in the browser. It parses the text definition, builds an internal graph or timeline representation, then calls a layout algorithm to position nodes before rendering to SVG. Mermaid uses Dagre for most directed graph layouts and a custom algorithm for Gantt charts. The layout is automatic: you declare nodes and edges; Mermaid decides where to place them. That trade-off gives diagrams that are fast to write but hard to fine-tune visually. ## Installing Mermaid and Rendering a First Diagram The npm package is named mermaid. Install it into a JavaScript project with: ```bash npm install mermaid ``` The package requires Node.js 22.12.0 or later, as declared in the repository's package.json engines field. For projects that do not manage npm packages, the library is available via the jsDelivr CDN listed in the README; the CDN URL is at jsdelivr.com/package/npm/mermaid. For contributors or people running the development environment from source, the repository uses pnpm as its package manager and Docker for an isolated build environment. The docker-compose.yml file maps port 3333 for the development server and reads the application port from a MERMAID_PORT environment variable. The Dockerfile uses node:22.12.0-alpine3.19 as the base image and sets NODE_OPTIONS to allow up to 8 GB of heap space for the build. GitHub renders Mermaid diagrams directly inside Markdown files and issue comments. To use it there, wrap the diagram definition in a fenced code block with the language set to mermaid: ```bash ```mermaid flowchart LR A-->B ``` ``` GitHub has supported this natively since February 2022, according to the GitHub blog post linked in the README. No plugin or extra step is needed for public or private repositories on github.com. ## The Live Editor for Rapid Iteration The Live Editor at mermaid.live lets anyone write and preview Mermaid diagrams in the browser without installing the library. The editor shows the source on the left and the rendered SVG on the right, updating as you type. The README links to two additional preview environments: a develop preview at develop.git.mermaid.live that shows the current state of the develop branch, and a next preview at next.git.mermaid.live for features staged for the following release. The Live Editor is the most practical starting point when evaluating whether Mermaid handles the diagram type you need. You can paste a definition, see how the layout engine positions nodes, and decide whether the automatic layout produces an acceptable result before committing to the library in a project. ## Layout Constraints and Cases Where Mermaid Falls Short The automatic layout is Mermaid's most significant limitation for complex diagrams. Dagre, the underlying library, places nodes algorithmically; you cannot assign x/y coordinates to individual nodes. In a flowchart with many crossing edges or tightly connected subgraphs, the result can be visually tangled in a way that cannot be corrected without restructuring the definition itself. There is no manual override for node position. Diagram type coverage is a second constraint. Network topology diagrams, floor plans, and anything that requires free-form shape placement are outside what Mermaid handles. The README's integration list shows where Mermaid works; platforms not on that list require verifying plugin support before relying on it for documentation. The library renders to SVG in a browser environment. Server-side rendering, such as pre-generating diagrams at build time for a static site, requires additional tooling. The mermaid-js organization maintains a CLI for this purpose, but it is a separate package not included in the main mermaid install. Version compatibility is a practical concern. Major versions have introduced syntax changes that broke existing diagrams. The repository includes a CHANGELOG.md file, and the mermaid@12.0.0 release on 2026-09-10 is the most recent major version. Diagrams written for an older major version may need syntax updates when upgrading. ## Comparison with PlantUML PlantUML is the most direct alternative for text-defined diagrams. Both tools take a text definition and produce a diagram, but they differ in architecture and hosting model. PlantUML is a Java application that generates PNG or SVG images server-side, which means a running Java process or a public PlantUML server is required to render diagrams. Mermaid runs in the browser as JavaScript, so no server component is needed for client-side rendering. PlantUML's text syntax uses a different notation and covers a wider set of UML diagram types, including component diagrams and deployment diagrams, which are not in Mermaid's standard set. PlantUML also allows more manual control over layout hints. The trade-off is that PlantUML diagrams do not render in GitHub Markdown natively; they require a proxy service or a CI step. Mermaid's GitHub integration requires no extra infrastructure, which makes it the lower-friction option for teams already using GitHub for documentation. ## Maintenance Status and License The repository is not archived. The last push was on 2026-09-21, and the mermaid@12.0.0 release was published on 2026-09-10. The release history in the repository also shows recent patch releases for the mermaid-zenuml and layout-tidy-tree subpackages on 2026-09-18, indicating that the sub-package ecosystem is being updated alongside the main library. The project is licensed under MIT. The MIT license permits use in commercial products and closed-source applications without requiring the source to be made available. The FUNDING.json and the CITATION.cff files in the repository indicate that the project accepts sponsorship and asks for academic citations, but neither imposes an obligation on users. The monorepo uses pnpm workspaces and is split across multiple packages under the packages/ directory. Contributors work from the develop branch, and the CONTRIBUTING.md file documents the development workflow. The .changeset/ directory shows the project uses Changesets for managing version bumps across packages. ## Conclusion Mermaid is a practical choice for engineering teams that write documentation in Markdown and want diagrams to live in version control. The direct GitHub integration removes any external tooling step for simple flowcharts and sequence diagrams. Teams with complex visual requirements, such as precise layout control or pixel-accurate export for print, will find the automatic layout engine limiting. Before adopting it, verify that the diagram types you need are covered by checking the documentation at mermaid.ai, and confirm that your documentation platform supports the Mermaid renderer or a compatible plugin. ## FAQ ### How do I use Mermaid in VS Code? VS Code does not render Mermaid diagrams natively, but the README lists integrations and community plugins. The most common approach is to install a Markdown preview extension that includes a Mermaid renderer, then write diagram definitions in fenced code blocks with the mermaid language tag inside a Markdown file. ### How do I install Mermaid? Install the npm package with npm install mermaid in a Node.js project. For projects without npm, the library is available from the jsDelivr CDN, as linked in the README. Node.js 22.12.0 or later is required. ### How do I use Mermaid diagrams in my project? After installing the npm package, import and initialize the library in your JavaScript bundle, then place diagram definitions in fenced mermaid code blocks in your Markdown files. GitHub renders these natively; other platforms need a Mermaid plugin or the CLI for pre-rendered output. ### How do I use Mermaid in Confluence? Confluence does not include a built-in Mermaid renderer. The README's integration list covers community and marketplace plugins for Confluence that add Mermaid support. The specific plugin to use depends on whether you are running Confluence Cloud or a self-hosted Confluence Data Center instance. ### How do I use Mermaid in Obsidian? Obsidian includes native Mermaid rendering in its Markdown preview. Write a diagram definition inside a fenced code block with the mermaid language tag, switch to preview mode, and Obsidian renders it as an SVG. No plugin is required for basic diagram types. ## Sources - [Official documentation](https://mermaid.ai/open-source/) - [Official README](https://github.com/mermaid-js/mermaid#readme) - [Project repository](https://github.com/mermaid-js/mermaid) - [Release notes](https://github.com/mermaid-js/mermaid/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mermaid-js-mermaid