# Mermaid.js: Create Beautiful Diagrams with Simple Markdown-Like Syntax
Mermaid.js is basically a JavaScript tool that lets you create diagrams using text - kinda like how Markdown works for formatting. Instead of dragging boxes around and getting frustrated when they won’t align properly, you just write some simple text, and boom - you get a professional-looking diagram.
What I really love about it is how it bridges the gap between different teams. Developers can use it, but so can project managers and writers. Since everything’s just text, you can keep your diagrams in version control alongside your code. Super handy for tech documentation!
Getting Mermaid up and running isn’t complicated at all. There’s a few different ways to do it depending on what you need.
Just add this script tag to your HTML file:
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
Then create your diagram with a div that has the “mermaid” class:
<div class="mermaid">
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
</div>
If your working with Node.js or using bundlers:
npm install mermaid
Then import it and initialize in your JS file:
import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: true });
Need to generate PNG files? Try this:
npm install -g @mermaid-js/mermaid-cli
And then you can use it like:
mmdc -i input.mmd -o output.png
Mermaid can handle quite a few diagram types - more than I initially expected!
You just describe what you want, and Mermaid figures out how to display it. This means you can focus on what’s important - the content - not fiddling with pixels and alignment for hours!
Here are some diagrams that are commonly used:
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
This makes a simple flowchart with decision points. The syntax is pretty intuitive once you get used to it:
graph TD
means “make a top-down graph”-->
syntax[]
gives you rectangles and {}
makes diamondssequenceDiagram
participant Browser
participant Server
Browser->>Server: GET /api/data
Server->>Database: SELECT * FROM data
Database-->>Server: Return results
Server-->>Browser: Send JSON response
This shows how a browser, server, and database interact:
sequenceDiagram
to tell Mermaid what you’re makinggantt
title Development Roadmap
dateFormat YYYY-MM-DD
section Planning
Requirements gathering :done, a1, 2023-01-01, 10d
System design :active, a2, after a1, 15d
section Implementation
Frontend development :b1, after a2, 20d
Backend development :b2, after a2, 25d
section Testing
Integration testing :c1, after b1, 5d
They show:
classDiagram
class Animal {
+String name
+int age
+makeSound() void
}
class Dog {
+fetch() void
}
class Cat {
+climb() void
}
Animal <|-- Dog
Animal <|-- Cat
This is really handy for showing:
Here’s what these diagrams actually look like when rendered:
A basic flowchart with decision logic
Sequence diagram showing how systems interact - helpful for API docs
Gantt chart for project planning
Class diagram showing inheritance - great for OOP design discussions
Here are some common use cases for mermaid.js:
Mermaid.js has completely changed how I handle diagrams in my technical docs. It solves so many headaches:
If you write technical docs, work in development, or need to plan projects, you should definitely give it a try. The learning curve isn’t steep at all, but what you can do with it is pretty impressive.
Whether you’re mapping out a complex system architecture, planning project timelines, or just trying to explain a process, Mermaid.js lets you create clear diagrams without leaving your text editor.