Guide · Open source
How to use Mermaid: write diagrams as text with npm install mermaid
Updated · written with AI from the project's own documentation and checked against our catalogue data
Mermaid is an open-source JavaScript tool that turns short, Markdown-inspired text descriptions into diagrams such as flowcharts and sequence diagrams. This guide explains what it is good for, how to install it with npm, and where to try it without installing anything. By the end you will know how to write a diagram as plain text and decide whether Mermaid fits your documentation workflow.
Mermaidmermaid-js/mermaid · ★ 91k · MIT Install options & downloads Quick start
- 1Open the Live Editor. Go to the Mermaid Live Editor to test diagram text without installing anything.
- 2Write a small diagram. Enter a flowchart or sequence diagram using the Markdown-inspired syntax from the documentation.
- 3Check the output. Adjust the text until the rendered diagram matches what you intend.
- 4Install the package. In your project folder, run npm install mermaid. Node.js is a prerequisite.
- 5Add the diagram to your docs or build. Store the diagram text in your Markdown or build script so it stays editable as plain text.
What Mermaid does and who it is for
Mermaid is a diagramming and charting tool. You describe a diagram in text, and a renderer draws it. Because the diagram lives as text, it can be edited, reviewed and versioned like the rest of your documentation.
The project's stated purpose is to help documentation keep up with development. Diagramming and docs take developer time and go out of date quickly, and Mermaid is meant to make diagrams easy to modify.
- Developers who want diagrams stored as text alongside code and docs
- Teams whose documentation is written in Markdown and needs diagrams
- Non-programmers who want to make diagrams in the Live Editor
- Projects that generate documentation as part of a build or production script
Install Mermaid with npm
Mermaid is distributed as an npm package. The README lists Node.js as the prerequisite; it does not state a minimum Node.js version, so check the npm package page or documentation for that detail.
Run the install command in your project folder:
npm install mermaidTry Mermaid in the Live Editor first
If you do not want to install anything, the Mermaid Live Editor lets you write diagram text and see the result immediately. The README describes it as the way non-programmers can create detailed diagrams.
The README also links to Develop and Next preview editors that try future releases. These are previews, so use the main Live Editor for stable work.
Write your first diagram in text
Mermaid uses a Markdown-inspired syntax. Each diagram type has its own keywords, and the full syntax is documented on the official documentation site. The examples in the source material are flowcharts and sequence diagrams, which are the types named in the project description.
Start in the Live Editor, paste a small definition, and change it until the output matches what you need. Then copy the same text into your project.
Use Mermaid inside Markdown and other tools
The README notes that Mermaid can be used within GitHub and many other applications. The project maintains a list of integrations and usages on its documentation site, which is the place to check whether your editor or platform supports it.
For video walkthroughs, the README points to a Tutorials page on the documentation site.
- Check the integrations list before assuming a platform renders Mermaid
- Use the Beginner's Guide and Usage pages for the basics
Know the limits before you commit
Mermaid is built around text input. The README positions it for text-defined diagrams rendered by a renderer, so it is not a tool for pixel-precise, freeform illustration. If your main workflow is drag-and-drop editing, a visual editor will likely suit you better.
Mermaid also includes a section on security and safe diagrams in its README, which is worth reading if you render diagrams from untrusted input.
What people use it for
- Flowcharts that document a process in a project README or wiki
- Sequence diagrams that show how services call each other
- Diagrams generated as part of a documentation build or production script
- Non-programmer diagrams drafted in the Live Editor and shared as text
Frequently asked questions
Is Mermaid free to use?
Mermaid is open source and released under the MIT licence, as listed in the project summary. The MIT licence generally allows use, modification and redistribution, but read the licence text itself for the exact terms.
How do I install Mermaid?
Mermaid is installed as an npm package. Run npm install mermaid in your project folder. Node.js is listed as the prerequisite.
Do I need to install anything to try Mermaid?
No. The Mermaid Live Editor lets you write diagram text and see the result in your browser.
Can I use Mermaid in Markdown files?
The README says Mermaid can be used within GitHub and many other applications. Check the project's integrations list to confirm support for your platform.
What is the difference between Mermaid and PlantUML?
Both generate diagrams from text. PlantUML, Graphviz and D2 are listed as comparable projects in our analysis, but this guide does not compare their features in detail. Test the syntax of each on a real diagram before choosing.
Why does my Mermaid diagram not render?
The source material does not include a troubleshooting guide. Check your syntax against the documentation, test the same text in the Live Editor, and consult the project's documentation or Discord community linked from the README.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Mermaid suits developers and teams who keep documentation in Markdown and want diagrams stored as editable text, including diagrams generated during a build. It is a poor fit if you need pixel-precise illustration or a drag-and-drop editor as your main workflow.
Install options & downloads