mermaid-diagramsCreates clear, web-savvy MermaidJS diagrams (flowcharts, sequence diagrams, Gantt charts, and more) for Markdown documentation that renders beautifully on GitHub.
Independent GitHub snapshot · Automated classification · Original documentation governs
name: mermaid-diagrams description: Creates clear, web-savvy MermaidJS diagrams (flowcharts, sequence diagrams, Gantt charts, and more) for Markdown documentation that renders beautifully on GitHub. license: MIT compatibility: opencode metadata: version: "1.0.0" domain: writing triggers: mermaid, mermaidjs, diagram, flowchart, sequence diagram, how do i create a diagram, github markdown diagram, architecture diagram a diagram archetypes:
Teaches AI models to write clean, well-structured MermaidJS diagrams that render beautifully on GitHub's native Markdown viewer. Covers diagram type selection, syntax best practices, GitHub-specific constraints, and common pitfalls across 10+ diagram types — flowcharts, sequence diagrams, Gantt charts, mindmaps, and more.
flowchart over graph — graph is deprecated in Mermaid→), em dashes (—), or smart quotes<br/> (not \n) for line breaks inside node labels--- frontmatter block at the top ```mermaid (lowercase) code fence — uppercase Mermaid won't render on GitHubUse this skill when:
Avoid this skill for:
Choose the Right Diagram Type — Match the concept you're visualizing to the correct Mermaid diagram type:
flowchartsequenceDiagramstateDiagram-v2classDiagramerDiagramganttgitGraphmindmaptimelinequadrantChartC4Context, C4Container, C4ComponentpiejourneyrequirementDiagramblocksankeyxyChartCheckpoint: If you can describe your diagram in one sentence as "X shows how Y does Z" the type is probably right. If you need three sentences, split into two diagrams.
Plan the Layout Direction — Choose the layout that matches your narrative flow:
direction TB or direction LR inside subgraphs to mix layouts for complex diagrams.Checkpoint: If your diagram has more vertical depth than horizontal width, use TD. If it's wider than tall, use LR.
Structure Nodes with Descriptive IDs — Use meaningful, CamelCase IDs that document themselves:
%% ✅ GOOD — IDs describe the component
flowchart TD
AuthService --> Database
AuthService --> CacheLayer
%% ❌ BAD — IDs are meaningless
flowchart TD
A1 --> B2
A1 --> C3
%% comments to document parts of the diagram for future maintainers<br/> for longer textAdd Edge Labels for Clarity — Every edge that represents a meaningful transition gets a label:
flowchart LR
Client -- "sends request" --> API
API -- "validates token" --> Auth
API -- "queries data" --> Database
-- "label text" --> or --|label text|--> for short labelsTest in the Mermaid Live Editor — Before committing, paste the entire block into mermaid.live:
end keywords, unmatched quotes, or IDs with spaces| Type | Best Use Case | GitHub Notes | Example |
|---|---|---|---|
flowchart | Processes, pipelines, decision trees, architecture flows | Most common type; flowchart preferred over deprecated graph | CI/CD pipeline with build → test → deploy stages |
sequenceDiagram | API calls, time-ordered interactions, message passing | Auto-numbers participants; use actor for human roles | Client → Auth server → API → Database request flow |
classDiagram | Data models, class hierarchies, interface contracts | Limited to ~15 classes before layout gets crowded | User, Order, Product with relationships and cardinality |
stateDiagram-v2 | State machines, UI workflows, lifecycle management | Use [*] for start/end states | Order lifecycle: Created → Paid → Shipped → Delivered |
erDiagram | Entity-relationship models, database schemas | Supports cardinality notation; keep under 10 entities | Customers, Orders, Products with ` |
gantt | Project timelines, schedules, release planning | Date format: YYYY-MM-DD; use crit for critical path | Sprint timeline with epics, tasks, and milestones |
pie | Proportions, market share, resource allocation | Simple format; titles shown as legend | Language usage: 60% TypeScript, 25% Python, 15% Go |
gitGraph | Branch strategies, merge workflows, release history | Branches auto-order by first commit; use cherry-pick | Feature branch → develop → main with release tags |
mindmap | Brainstorming, knowledge hierarchies, outlines | Indentation-driven syntax; no edge labels | Project architecture with backend, frontend, infra branches |
timeline | Chronological events, roadmaps, histories | Sections group related events; limited styling | Product roadmap: Q1 MVP → Q2 Beta → Q3 GA |
quadrantChart | Prioritization matrices, SWOT analysis, portfolio | Points positioned by X/Y values (0–1 range); quadrant labels in config | Feature priority: effort vs impact |
C4Context | System context diagrams (C4 model) | Uses Person and System boundaries; good for high-level architecture | User → System A → System B interactions |
block | Category-based flow diagrams | Columns group related blocks; simple structure | Tech stack: Languages, Frameworks, Tools in columns |
journey | User experience flows, task completion steps | Auto-scales; tasks listed in order with scores | User onboarding: signup → verify → dashboard |
Use lowercase ```mermaid — GitHub only renders lowercase. Uppercase ```Mermaid or ```mmd will not render.
<!-- ✅ WORKS on GitHub -->
```mermaid
flowchart TD
A --> B
flowchart TD
A --> B
### Feature Restrictions
GitHub's native Mermaid renderer removes or ignores certain features. Know these limitations before you write:
| Feature | GitHub Support | Workaround |
|---------|---------------|------------|
| Click events (`click A callback`) | ❌ Stripped | Add text links outside the diagram instead |
| Tooltips (title attribute on nodes) | ❌ Stripped | Add explanation in surrounding prose |
| Theme config via `%%{init:...}` | ⚠️ Config ignored | GitHub uses system light/dark mode; test both |
| `fontSize`, `fontFamily` in config | ⚠️ Partially respected | Keep labels short — default font is always readable |
| Markdown strings (`"..."`) | ✅ Supported | Use for bold/italic/`code` in labels |
| Subgraph styling | ✅ Supported | Use `style` or `classDef` for consistent coloring |
### Size Limit
Diagrams over approximately **50KB** in source text may fail to render on GitHub. As a rule of thumb:
- Keep diagrams under 20–25 nodes
- Keep labels under ~25 characters when possible
- If you need more nodes, split into multiple smaller diagrams that each cover one concept
- Diagrams over 50KB are silently dropped — you get no error message
### Theme Adaptation
GitHub renders Mermaid in the **viewer's system theme** (light or dark mode). You cannot force a specific theme. Design diagrams that work in both:
- Do **not** rely on color alone to convey meaning — always add text labels or patterns
- Use high-contrast combinations (dark text on light backgrounds, light text on dark backgrounds)
- Test in both modes by toggling your OS/browser theme before pushing
### Testing Protocol
Before committing any Mermaid diagram:
1. Paste the full code block into [mermaid.live](https://mermaid.live) — fix any parse errors
2. Copy the rendered output as a PNG and verify it reads well at a glance
3. Toggle your system theme and re-check contrast
4. If the diagram is complex, ask a colleague to describe what they see in 1–2 sentences — if they can't, simplify
---
## Syntax Reference
### Node Shapes
| Shape | Syntax | Example |
|-------|--------|---------|
| Default rectangle | `id[label]` | `Server[Web Server]` |
| Rounded rectangle | `id(label)` | `API(API Gateway)` |
| Stadium (pill shape) | `id([label])` | `Start([Begin Process])` |
| Rhombus (decision) | `id{label}` | `Auth{Is Valid?}` |
| Parallelogram | `id[\\label\\]` | `Input[\\Parse Data\\]` |
| Trapezoid | `id[/label\\]` | `Service[/Transform\\]` |
| Double circle | `id(((label)))` | `End(((System Halt)))` |
| Asymmetric | `id>label]` | `Output>Result]` |
| Hexagon | `id{{label}}` | `Routing{{Load Balance}}` |
### Edge Styles
| Style | Syntax | Use Case |
|-------|--------|----------|
| Solid arrow | `-->` | Default flow, data passing |
| Thick arrow | `==>` | Primary/critical path |
| Dotted arrow | `-.->` | Optional/monitoring/async flow |
| Open circle | `--o` | UML aggregation or "uses" |
| Cross | `--x` | Error path, termination |
| Bidirectional | `<-->` | Two-way communication |
| Label (inline) | `-- "text" -->` | Standard edge labels |
| Label (short) | `--\|text\|-->` | Compact labels |
### Subgraph Structure
Wrap related nodes in a `subgraph` block with an optional `direction` override:
```mermaid
flowchart TD
subgraph Frontend["Frontend Layer"]
direction LR
A[React App] --> B[API Client]
end
subgraph Backend["Backend Services"]
direction TB
C[Auth Service] --> D[Database]
C --> E[Cache]
end
B --> C
Rules:
subgraph needs a closing end keyword — forgetting end is the most common Mermaid syntax errorsubgraph Name["Display Name"] if the display name differs from the ID or contains special charactersdirection TB/LR) is optional — without it, the subgraph inherits the parent's directionUse %% for single-line comments. Comments are ignored by the renderer but visible in source:
%% This diagram shows the user authentication flow
flowchart TD
%% Entry point
Login --> Auth{Valid Credentials?}
Auth -- Yes --> Dashboard
Auth -- No --> LoginError
Apply CSS-like classes to nodes for consistent visual grouping:
flowchart TD
classDef primary fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef danger fill:#ffebee,stroke:#b71c1c
A[Login] --> B[Dashboard]
C[Error Handler] --> D[Fallback]
class A,B primary
class C,D danger
Alternatively, use inline style for one-off nodes:
flowchart TD
A[Critical Component] --> B[Normal Component]
style A fill:#ffebee,stroke:#c62828,stroke-width:4px
Use double-quoted markdown strings to include bold, italic, or code formatting in node labels:
flowchart LR
A["**Build** the _package_"] --> B["Run `npm test`"]
Supported formatting inside markdown strings: **bold**, *italic*, `code`.
Line breaks inside markdown strings: use <br/> not \n.
Set global rendering options with a YAML block at the top of the diagram:
---
config:
theme: neutral
flowchart:
curveBasis: 0.3
---
flowchart TD
A --> B
Available themes: default, forest, dark, neutral, base.
Use base as a starting point for custom themes with themeVariables.
A top-down flowchart showing a CI/CD deployment pipeline with subgraphs for each stage. Uses TD direction for the natural reading flow from commit to production.
---
config:
theme: neutral
---
flowchart TD
subgraph Source["Source Control"]
direction LR
Dev[Developer] --> PR[Pull Request]
PR --> Review[Code Review]
Review --> Merge[Merge to Main]
end
subgraph CI["Continuous Integration"]
direction TB
Merge --> Lint[Lint & Type Check]
Lint --> Test[Run Tests]
Test --> Build[Build Artifact]
end
subgraph CD["Continuous Deployment"]
direction TB
Build --> Staging[Deploy to Staging]
Staging --> E2E[E2E Tests]
E2E --> Approve{Approved?}
Approve -- Yes --> Prod[Deploy to Production]
Approve -- No --> Rollback[Rollback]
end
%% Cross-stage styling
classDef ci fill:#e3f2fd,stroke:#1565c0
classDef cd fill:#e8f5e9,stroke:#2e7d32
classDef gate fill:#fff3e0,stroke:#e65100
class Lint,Test,Build ci
class Staging,E2E,Prod cd
class Approve,Rollback gate
Key design choices:
direction LR in Source keeps the PR flow compact horizontallyApprove) marks the manual gating stepA sequence diagram showing how a client, auth service, API gateway, and database interact during a token-based request. Reads left-to-right as time progresses downward.
sequenceDiagram
actor User
participant Client as Web Client
participant Auth as Auth Service
participant API as API Gateway
participant DB as Database
User->>Client: Submit credentials
Client->>Auth: POST /auth/token
Auth->>Auth: Validate credentials
Auth-->>Client: Return JWT token
Note over Client,Auth: Token cached for 15 minutes
Client->>API: GET /api/resource<br/>Authorization: Bearer JWT
API->>Auth: Verify token signature
Auth-->>API: Token valid (payload)
API->>DB: SELECT * FROM resources
DB-->>API: Return results
API-->>Client: 200 OK + JSON body
Client-->>User: Display resources
alt Token Expired
Client->>Auth: POST /auth/refresh
Auth-->>Client: New JWT token
end
Key design choices:
actor User distinguishes the human role from system participants-->>) for responses, solid lines (->>) for requests — standard conventionNote over documents the token caching behavior inline<br/> in the API request label keeps the readable content on one linealt block handles the token refresh edge case without cluttering the main flowTwo subgraphs side by side (LR direction) comparing a naive architecture against an improved one. Useful for RFCs, ADRs, or refactoring proposals.
---
config:
theme: neutral
---
flowchart LR
subgraph Before["Before: Monolithic"]
direction TB
Monolith[Single App Server]
MonolithDB[(Single Database)]
Monolith --> MonolithDB
Monolith --- Monolith
end
subgraph After["After: Microservices"]
direction TB
API[API Gateway]
Users[User Service]
Orders[Order Service]
Notify[Notification Service]
UserDB[(User DB)]
OrderDB[(Order DB)]
API --> Users
API --> Orders
Users --> UserDB
Orders --> OrderDB
Orders -.-> Notify
end
style Before fill:#ffebee,stroke:#c62828,stroke-width:2px,stroke-dasharray: 5 5
style After fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
Key design choices:
A complex architecture diagram that combines TD and LR directions in nested subgraphs. Shows how direction directives can create readable multi-region layouts.
---
config:
theme: base
themeVariables:
primaryColor: "#f5f5f5"
primaryBorderColor: "#333"
lineColor: "#666"
---
flowchart TB
subgraph ClientLayer["Client Layer"]
direction LR
Web[Web App]
Mobile[Mobile App]
CLI[CLI Tool]
end
subgraph Gateway["API Gateway"]
LB[Load Balancer]
Rate[Rate Limiter]
LB --> Rate
end
subgraph Services["Microservices"]
direction TB
subgraph Auth["Auth Domain"]
Login[Login Service]
Token[Token Service]
end
subgraph Data["Data Domain"]
Query[Query Service]
Write[Write Service]
Cache[Cache Layer]
end
subgraph Jobs["Background Jobs"]
Worker1[Report Worker]
Worker2[Sync Worker]
end
end
subgraph Storage["Data Stores"]
direction LR
PG[(PostgreSQL)]
Redis[(Redis)]
S3[(Object Store)]
end
%% Connections between layers
Web --> LB
Mobile --> LB
CLI --> LB
Rate --> Login
Rate --> Query
Rate --> Write
Login --> Token
Query --> PG
Query --> Redis
Write --> PG
Write --> S3
Worker1 --> PG
Worker2 --> Redis
classDef client fill:#e3f2fd,stroke:#1565c0
classDef gateway fill:#fff3e0,stroke:#e65100
classDef domain fill:#f3e5f5,stroke:#7b1fa2
classDef storage fill:#e8f5e9,stroke:#2e7d32
class Web,Mobile,CLI client
class LB,Rate gateway
class Login,Token,Query,Write,Cache,Worker1,Worker2 domain
class PG,Redis,S3 storage
Key design choices:
ClientLayer and Storage keeps those layers horizontally compactServices group domains without creating a new top-level layerbase theme with custom themeVariables for a neutral, professional lookflowchart over graph — graph is deprecated. All new diagrams should use flowchart.""), em dashes (—), en dashes (–), Unicode arrows (→, ↔, ⇒), and non-ASCII punctuation break Mermaid's parser. Use straight quotes (""), hyphens (-), and ASCII arrows (-->, <-->, ==>) instead.<br/> for line breaks — Actual newlines inside quoted node labels or edge labels may produce parse errors.<br/> for longer labels.→, —, –, ✓, ✗ silently break Mermaid rendering. Use -->, ->, -, x, v or simple ASCII alternatives.click callbacks, tooltip attributes, and target links are stripped by GitHub. Put links in the surrounding Markdown instead.```mermaid block must contain exactly one diagram type. If you need a flowchart and a sequence diagram, use two separate blocks with separate descriptions.\n for line breaks — Mermaid expects <br/> for line breaks inside labels. The \n escape sequence is not supported inside quoted strings.[My Service] or [data:flow] will fail. Use CamelCase instead: MyService, DataFlow.When asked to create a Mermaid diagram, produce:
Diagram Type & Purpose — One sentence explaining what the diagram shows and why it's the right type for this content (e.g., "A TD flowchart showing the CI/CD pipeline from commit to production deployment.")
Code Block — The complete Mermaid diagram code inside a ```mermaid code fence. Include a --- config block if theme or layout tweaks are needed.
Legend / Key — If using semantic colors, custom classes, or abbreviations in node IDs, include a brief legend explaining them. For simple diagrams, a one-sentence description suffices.
Template:
<!-- Explanation -->
<!-- [Diagram Type] showing [what it represents] -->
```mermaid
[diagram code]
**Example:**
```markdown
A TD flowchart showing the user authentication flow from login request to dashboard access.
```mermaid
flowchart TD
A[Login Request] --> B{Valid Credentials?}
B -- Yes --> C[Dashboard]
B -- No --> D[Error Page]
style C fill:#e8f5e9,stroke:#2e7d32
style D fill:#ffebee,stroke:#c62828
Legend: Green nodes represent success states, red nodes represent error states.
---
## Related Skills
| Skill | Purpose |
|-------|---------|
| `technical-documentation` | Writing the prose that surrounds and explains your Mermaid diagrams — READMEs, API docs, architecture overviews |