Mermaid Diagramming
Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.
Core Syntax Structure
All Mermaid diagrams follow this pattern:
diagramType
definition content
Key principles:
- First line declares diagram type (e.g.,
classDiagram, sequenceDiagram, flowchart)
- Use
%% for comments
- Line breaks and indentation improve readability but aren't required
- Unknown words break diagrams; parameters fail silently
Diagram Type Selection Guide
Choose the right diagram type:
Class Diagrams - Domain modeling, OOP design, entity relationships
- Domain-driven design documentation
- Object-oriented class structures
- Entity relationships and dependencies
Sequence Diagrams - Temporal interactions, message flows
- API request/response flows
- User authentication flows
- System component interactions
- Method call sequences
Flowcharts - Processes, algorithms, decision trees
- User journeys and workflows
- Business processes
- Algorithm logic
- Deployment pipelines
Entity Relationship Diagrams (ERD) - Database schemas
- Table relationships
- Data modeling
- Schema design
C4 Diagrams - Software architecture at multiple levels
- System Context (systems and users)
- Container (applications, databases, services)
- Component (internal structure)
- Code (class/interface level)
State Diagrams - State machines, lifecycle states
Git Graphs - Version control branching strategies
Gantt Charts - Project timelines, scheduling
Pie/Bar Charts - Data visualization
Quick Start Examples
Class Diagram (Domain Model)
classDiagram
Title -- Genre
Title *-- Season
Title *-- Review
User --> Review : creates
class Title {
+string name
+int releaseYear
+play()
}
class Genre {
+string name
+getTopTitles()
}
Sequence Diagram (API Flow)
sequenceDiagram
participant User
participant API
participant Database
User->>API: POST /login
API->>Database: Query credentials
Database-->>API: Return user data
alt Valid credentials
API-->>User: 200 OK + JWT token
else Invalid credentials
API-->>User: 401 Unauthorized
end
Flowchart (User Journey)
flowchart TD
Start([User visits site]) --> Auth{Authenticated?}
Auth -->|No| Login[Show login page]
Auth -->|Yes| Dashboard[Show dashboard]
Login --> Creds[Enter credentials]
Creds --> Validate{Valid?}
Validate -->|Yes| Dashboard
Validate -->|No| Error[Show error]
Error --> Login
ERD (Database Schema)
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
PRODUCT ||--o{ LINE_ITEM : includes
USER {
int id PK
string email UK
string name
datetime created_at
}
ORDER {
int id PK
int user_id FK
decimal total
datetime created_at
}
Detailed References
For in-depth guidance on specific diagram types, see:
- references/class-diagrams.md - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
- references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
- references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
- references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
- references/c4-diagrams.md - System context, container, component diagrams, boundaries
- references/state-diagrams.md - Lifecycle states, labelled transitions, aliases, composite states, choice/fork/join, concurrent regions, notes
- references/advanced-features.md - Themes, styling, configuration, layout options
Best Practices
- Start Simple - Begin with core entities/components, add details incrementally
- Use Meaningful Names - Clear labels make diagrams self-documenting
- Comment Extensively - Use
%% comments to explain complex relationships
- Keep Focused - One diagram per concept; split large diagrams into multiple focused views
- Version Control - Store
.mmd files alongside code for easy updates
- Add Context - Include titles and notes to explain diagram purpose
- Iterate - Refine diagrams as understanding evolves
Editorial Style Rules
Mermaid 자동 레이아웃을 쓰더라도 아래 규칙을 지키면 "AI 기본 출력" 느낌을 크게 줄일 수 있습니다
(diagram-design 모듈에서 이식한 압축본. 완전한 에디토리얼 렌더링이 필요하면
skills/diagram-design/SKILL.md 표현 계층을 사용하세요).
- 액센트는 1~2개 노드만:
classDef accent를 핵심 노드(happy path의 결정점, 최종 산출물)에만
적용. 모든 분기·에러에 색을 칠하면 신호가 사라집니다. 나머지는 기본 스타일 유지.
- 밀도 예산: 사람에게 보여줄 다이어그램은 노드 9개 이하 목표. 초과하면 개요 1장 + 상세 N장으로
분할합니다. (파이프라인 검증용
.mmd는 기존 20개 제한 유지 — 용도가 다름)
- 도형이 타입을 말하게: 시작/끝
([ ]), 처리 [ ], 분기 { }, 서브루틴 [[ ]].
색으로 노드 타입을 구분하지 않습니다.
- 분기 레이블 필수: decision에서 나가는 모든 화살표에
|Yes|/|No| 등 레이블. 출구 4개 이상인
분기는 중첩 분기로 리팩터링.
- 색 토큰: 순수
#000/#fff 대신 near-black(#2d3142)·off-white(#f5f5f5). 액센트는
프로젝트 DESIGN.md 토큰이 있으면 그것을, 없으면 한 가지 hue만.
---
config:
theme: base
themeVariables:
primaryColor: "#f5f5f5"
primaryTextColor: "#2d3142"
primaryBorderColor: "#4f5d75"
lineColor: "#4f5d75"
---
flowchart TD
A([시작]) --> B{유효?}
B -->|Yes| C[처리]
B -->|No| D[거부]
C --> E([완료])
classDef accent stroke:#eb6c36,stroke-width:2px
class E accent
Configuration and Theming
Configure diagrams using frontmatter:
---
config:
theme: base
themeVariables:
primaryColor: "#ff6b6b"
---
flowchart LR
A --> B
Available themes: default, forest, dark, neutral, base
Layout options:
layout: dagre (default) - Classic balanced layout
layout: elk - Advanced layout for complex diagrams (requires integration)
Look options:
look: classic - Traditional Mermaid style
look: handDrawn - Sketch-like appearance
Exporting and Rendering
Native support in:
- GitHub/GitLab - Automatically renders in Markdown
- VS Code - With Markdown Mermaid extension
- Notion, Obsidian, Confluence - Built-in support
Export options:
- Mermaid Live Editor - Online editor with PNG/SVG export
- Mermaid CLI -
npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png
- Docker -
docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png
Common Pitfalls
- Breaking characters - Avoid
{} in comments, use proper escape sequences for special characters
- Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
- Overcomplexity - Split complex diagrams into multiple focused views
- Missing relationships - Document all important connections between entities
When to Create Diagrams
Always diagram when:
- Starting new projects or features
- Documenting complex systems
- Explaining architecture decisions
- Designing database schemas
- Planning refactoring efforts
- Onboarding new team members
Use diagrams to:
- Align stakeholders on technical decisions
- Document domain models collaboratively
- Visualize data flows and system interactions
- Plan before coding
- Create living documentation that evolves with code
1---2name: mermaid-diagrams3description: "Create Mermaid software diagrams: flowcharts, sequence, class, ERD, C4, state, git, pie, and gantt; use for diagram, visualize, model, map out, show the flow, architecture, database, code, or user-flow docs."4metadata:5 source: https://skillmd.com/skills/dannykkh/mermaid-diagrams6---78# Mermaid Diagramming910Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.1112## Core Syntax Structure1314All Mermaid diagrams follow this pattern:1516```mermaid17diagramType18 definition content19```2021**Key principles:**22- First line declares diagram type (e.g., `classDiagram`, `sequenceDiagram`, `flowchart`)23- Use `%%` for comments24- Line breaks and indentation improve readability but aren't required25- Unknown words break diagrams; parameters fail silently2627## Diagram Type Selection Guide2829**Choose the right diagram type:**30311. **Class Diagrams** - Domain modeling, OOP design, entity relationships32 - Domain-driven design documentation33 - Object-oriented class structures34 - Entity relationships and dependencies35362. **Sequence Diagrams** - Temporal interactions, message flows37 - API request/response flows38 - User authentication flows39 - System component interactions40 - Method call sequences41423. **Flowcharts** - Processes, algorithms, decision trees43 - User journeys and workflows44 - Business processes45 - Algorithm logic46 - Deployment pipelines47484. **Entity Relationship Diagrams (ERD)** - Database schemas49 - Table relationships50 - Data modeling51 - Schema design52535. **C4 Diagrams** - Software architecture at multiple levels54 - System Context (systems and users)55 - Container (applications, databases, services)56 - Component (internal structure)57 - Code (class/interface level)58596. **State Diagrams** - State machines, lifecycle states607. **Git Graphs** - Version control branching strategies618. **Gantt Charts** - Project timelines, scheduling629. **Pie/Bar Charts** - Data visualization6364## Quick Start Examples6566### Class Diagram (Domain Model)67```mermaid68classDiagram69 Title -- Genre70 Title *-- Season71 Title *-- Review72 User --> Review : creates73 74 class Title {75 +string name76 +int releaseYear77 +play()78 }79 80 class Genre {81 +string name82 +getTopTitles()83 }84```8586### Sequence Diagram (API Flow)87```mermaid88sequenceDiagram89 participant User90 participant API91 participant Database92 93 User->>API: POST /login94 API->>Database: Query credentials95 Database-->>API: Return user data96 alt Valid credentials97 API-->>User: 200 OK + JWT token98 else Invalid credentials99 API-->>User: 401 Unauthorized100 end101```102103### Flowchart (User Journey)104```mermaid105flowchart TD106 Start([User visits site]) --> Auth{Authenticated?}107 Auth -->|No| Login[Show login page]108 Auth -->|Yes| Dashboard[Show dashboard]109 Login --> Creds[Enter credentials]110 Creds --> Validate{Valid?}111 Validate -->|Yes| Dashboard112 Validate -->|No| Error[Show error]113 Error --> Login114```115116### ERD (Database Schema)117```mermaid118erDiagram119 USER ||--o{ ORDER : places120 ORDER ||--|{ LINE_ITEM : contains121 PRODUCT ||--o{ LINE_ITEM : includes122 123 USER {124 int id PK125 string email UK126 string name127 datetime created_at128 }129 130 ORDER {131 int id PK132 int user_id FK133 decimal total134 datetime created_at135 }136```137138## Detailed References139140For in-depth guidance on specific diagram types, see:141142- **[references/class-diagrams.md](references/class-diagrams.md)** - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties143- **[references/sequence-diagrams.md](references/sequence-diagrams.md)** - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes144- **[references/flowcharts.md](references/flowcharts.md)** - Node shapes, connections, decision logic, subgraphs, styling145- **[references/erd-diagrams.md](references/erd-diagrams.md)** - Entities, relationships, cardinality, keys, attributes146- **[references/c4-diagrams.md](references/c4-diagrams.md)** - System context, container, component diagrams, boundaries147- **[references/state-diagrams.md](references/state-diagrams.md)** - Lifecycle states, labelled transitions, aliases, composite states, choice/fork/join, concurrent regions, notes148- **[references/advanced-features.md](references/advanced-features.md)** - Themes, styling, configuration, layout options149150## Best Practices1511521. **Start Simple** - Begin with core entities/components, add details incrementally1532. **Use Meaningful Names** - Clear labels make diagrams self-documenting1543. **Comment Extensively** - Use `%%` comments to explain complex relationships1554. **Keep Focused** - One diagram per concept; split large diagrams into multiple focused views1565. **Version Control** - Store `.mmd` files alongside code for easy updates1576. **Add Context** - Include titles and notes to explain diagram purpose1587. **Iterate** - Refine diagrams as understanding evolves159160## Editorial Style Rules161162Mermaid 자동 레이아웃을 쓰더라도 아래 규칙을 지키면 "AI 기본 출력" 느낌을 크게 줄일 수 있습니다163(diagram-design 모듈에서 이식한 압축본. 완전한 에디토리얼 렌더링이 필요하면164`skills/diagram-design/SKILL.md` 표현 계층을 사용하세요).165166- **액센트는 1~2개 노드만**: `classDef accent`를 핵심 노드(happy path의 결정점, 최종 산출물)에만167 적용. 모든 분기·에러에 색을 칠하면 신호가 사라집니다. 나머지는 기본 스타일 유지.168- **밀도 예산**: 사람에게 보여줄 다이어그램은 노드 9개 이하 목표. 초과하면 개요 1장 + 상세 N장으로169 분할합니다. (파이프라인 검증용 `.mmd`는 기존 20개 제한 유지 — 용도가 다름)170- **도형이 타입을 말하게**: 시작/끝 `([ ])`, 처리 `[ ]`, 분기 `{ }`, 서브루틴 `[[ ]]`.171 색으로 노드 타입을 구분하지 않습니다.172- **분기 레이블 필수**: decision에서 나가는 모든 화살표에 `|Yes|`/`|No|` 등 레이블. 출구 4개 이상인173 분기는 중첩 분기로 리팩터링.174- **색 토큰**: 순수 `#000`/`#fff` 대신 near-black(`#2d3142`)·off-white(`#f5f5f5`). 액센트는175 프로젝트 `DESIGN.md` 토큰이 있으면 그것을, 없으면 한 가지 hue만.176177```mermaid178---179config:180 theme: base181 themeVariables:182 primaryColor: "#f5f5f5"183 primaryTextColor: "#2d3142"184 primaryBorderColor: "#4f5d75"185 lineColor: "#4f5d75"186---187flowchart TD188 A([시작]) --> B{유효?}189 B -->|Yes| C[처리]190 B -->|No| D[거부]191 C --> E([완료])192 classDef accent stroke:#eb6c36,stroke-width:2px193 class E accent194```195196## Configuration and Theming197198Configure diagrams using frontmatter:199200```mermaid201---202config:203 theme: base204 themeVariables:205 primaryColor: "#ff6b6b"206---207flowchart LR208 A --> B209```210211**Available themes:** default, forest, dark, neutral, base212213**Layout options:**214- `layout: dagre` (default) - Classic balanced layout215- `layout: elk` - Advanced layout for complex diagrams (requires integration)216217**Look options:**218- `look: classic` - Traditional Mermaid style219- `look: handDrawn` - Sketch-like appearance220221## Exporting and Rendering222223**Native support in:**224- GitHub/GitLab - Automatically renders in Markdown225- VS Code - With Markdown Mermaid extension226- Notion, Obsidian, Confluence - Built-in support227228**Export options:**229- [Mermaid Live Editor](https://mermaid.live) - Online editor with PNG/SVG export230- Mermaid CLI - `npm install -g @mermaid-js/mermaid-cli` then `mmdc -i input.mmd -o output.png`231- Docker - `docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png`232233## Common Pitfalls234235- **Breaking characters** - Avoid `{}` in comments, use proper escape sequences for special characters236- **Syntax errors** - Misspellings break diagrams; validate syntax in Mermaid Live237- **Overcomplexity** - Split complex diagrams into multiple focused views238- **Missing relationships** - Document all important connections between entities239240## When to Create Diagrams241242**Always diagram when:**243- Starting new projects or features244- Documenting complex systems245- Explaining architecture decisions246- Designing database schemas247- Planning refactoring efforts248- Onboarding new team members249250**Use diagrams to:**251- Align stakeholders on technical decisions252- Document domain models collaboratively253- Visualize data flows and system interactions254- Plan before coding255- Create living documentation that evolves with code