# Mermaid — Generate Diagrams from Text Like Markdown

> Mermaid is a JavaScript-based diagramming tool that renders Markdown-inspired text definitions to create diagrams and visualizations. Flowcharts, sequence diagrams, Gantt charts, class diagrams, ER diagrams, and more — all from plain text. Natively supported in GitHub Markdown.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

In GitHub Markdown (natively supported):
````markdown
```mermaid
flowchart TD
    A[User visits site] --> B{Logged in?}
    B -->|Yes| C[Dashboard]
    B -->|No| D[Login page]
    D --> E[Enter credentials]
    E --> B
```
````

Programmatic usage:
```bash
npm i mermaid
```

```html
<script type="module">
  import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
  mermaid.initialize({ startOnLoad: true, theme: "dark" });
</script>

<pre class="mermaid">
sequenceDiagram
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: user record
    API-->>Client: JWT token
</pre>
```

CLI rendering:
```bash
npm i -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg -t dark
mmdc -i input.mmd -o output.png -w 1200
```

## Intro

Mermaid is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. Created by Knut Sveidqvist. Natively supported in GitHub Markdown, GitLab, Notion, Obsidian, Docusaurus, and many other platforms. Lets developers create documentation diagrams without Figma or draw.io.

- **Repo**: https://github.com/mermaid-js/mermaid
- **Stars**: 87K+
- **Language**: TypeScript
- **License**: MIT

## What Mermaid Does

- **Flowcharts** — TD, LR, RL, BT directions
- **Sequence diagrams** — actor interactions with arrows
- **Class diagrams** — UML-style
- **State diagrams** — state machine flows
- **ER diagrams** — entity-relationship
- **Gantt charts** — project timelines
- **Pie charts** — data distribution
- **Git graphs** — branch visualization
- **Mindmaps** — hierarchical thinking
- **Timeline** — chronological events
- **Quadrant charts** — 2x2 matrices
- **Block diagrams** — architecture views

## Architecture

Pure JavaScript/TypeScript library. Parses Mermaid syntax → builds internal graph → renders to SVG via dagre (layout algorithm) and D3 (rendering). Can run in browser, Node.js, or CLI.

## Self-Hosting

Client-side library, no backend.

## Key Features

- 15+ diagram types
- GitHub Markdown native
- Dark and light themes
- CLI for CI/CD rendering
- Customizable via directives
- Live editor (mermaid.live)
- Plugin for Docusaurus, Obsidian, Notion
- SVG and PNG export
- Accessible (ARIA labels)

## Comparison

| Tool | Input | Types | Integration |
|---|---|---|---|
| Mermaid | Text | 15+ | GitHub, GitLab, Notion |
| PlantUML | Text | 15+ | Java-based |
| draw.io | GUI | Any | Web, desktop |
| Excalidraw | GUI | Freeform | Web |
| D2 | Text | 10+ | CLI |

## FAQ

**Q: How to use it on GitHub?**
A: Write a ```mermaid code block directly in a Markdown file and GitHub will render it automatically. No install needed.

**Q: Compared to PlantUML?**
A: Mermaid is pure JS (native to browsers); PlantUML requires a Java backend. Mermaid syntax is more concise; PlantUML has more complete features (stronger activity diagrams).

**Q: Can you customize the styling?**
A: Yes. Use `%%{init: {"theme": "forest"}}%%` or bind a CSS class. Fully custom theme JSON is also supported.

## Sources

- Docs: https://mermaid.js.org/intro
- GitHub: https://github.com/mermaid-js/mermaid
- License: MIT

---
Source: https://tokrepo.com/en/workflows/mermaid-generate-diagrams-text-like-markdown-90331916
Author: AI Open Source