# 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 in your project root:

## 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: GitHub 里怎么用？**
A: 直接在 Markdown 文件中写 ````mermaid` 代码块，GitHub 自动渲染。无需安装任何东西。

**Q: 和 PlantUML 比？**
A: Mermaid 纯 JS（浏览器原生），PlantUML 需要 Java 后端。Mermaid 语法更简洁，PlantUML 功能更完整（活动图更强）。

**Q: 能定制样式吗？**
A: 可以。用 `%%{init: {"theme": "forest"}}%%` 或 CSS class 绑定。也支持完全自定义 theme JSON。

## 来源与致谢 Sources

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

---
Source: https://tokrepo.com/en/workflows/90331916-3649-11f1-9bc6-00163e2b0d79
Author: AI Open Source