Mermaid로 마크다운에서 다이어그램 그리기
Mermaid로 마크다운에서 다이어그램 그리기
문서를 작성하다 보면 복잡한 로직이나 시스템 구조를 설명해야 할 때가 있습니다. 이럴 때 텍스트만으로 설명하면 이해하기 어렵고, 이미지 파일을 만들자니 수정이 번거롭습니다.
Mermaid는 텍스트 기반으로 다이어그램을 생성하는 JavaScript 라이브러리입니다. 마크다운 코드 블록 안에 간단한 문법으로 작성하면 자동으로 다이어그램이 렌더링됩니다.
Mermaid란?
Mermaid는 마크다운에서 영감을 받은 텍스트 정의를 사용하여 다이어그램을 생성하는 도구입니다. GitHub, GitLab, Notion, Obsidian 등 많은 플랫폼에서 기본 지원하며, 다음과 같은 장점이 있습니다:
- 버전 관리 가능: 텍스트 기반이므로 Git으로 변경 이력 추적 가능
- 수정이 간편: 이미지 편집 도구 없이 텍스트만 수정하면 됨
- 일관된 스타일: 자동으로 정렬되고 동일한 스타일 적용
- 다양한 차트 지원: 플로우차트, 시퀀스 다이어그램, 간트 차트 등
현재 Mermaid v11 기준으로 작성되었습니다.
기본 사용법
마크다운에서 코드 블록의 언어를 mermaid로 지정하면 됩니다:
```mermaid flowchart TD A[시작] --> B[처리] B --> C[끝] ```
위 코드는 다음과 같이 렌더링됩니다:
플로우차트 (Flowchart)
가장 많이 사용하는 다이어그램으로, 프로세스 흐름을 표현합니다. flowchart 키워드를 사용합니다 (구버전의 graph도 호환됨).
방향 설정
TB또는TD: 위에서 아래로 (Top to Bottom / Top Down)BT: 아래에서 위로 (Bottom to Top)LR: 왼쪽에서 오른쪽으로 (Left to Right)RL: 오른쪽에서 왼쪽으로 (Right to Left)
노드 모양
다양한 모양의 노드를 사용할 수 있습니다:
| 문법 | 모양 | 용도 |
|---|---|---|
[텍스트] | 사각형 | 일반 프로세스 |
(텍스트) | 둥근 사각형 | 일반 단계 |
([텍스트]) | 스타디움 | 시작/종료 |
[[텍스트]] | 서브루틴 | 함수/서브프로세스 |
[(텍스트)] | 데이터베이스 | 데이터 저장소 |
((텍스트)) | 원형 | 연결점 |
{텍스트} | 다이아몬드 | 조건 분기 |
{{텍스트}} | 육각형 | 준비 단계 |
[/텍스트/] | 평행사변형 | 입력/출력 |
[\텍스트\] | 역평행사변형 | 수동 작업 |
연결선 스타일
| 문법 | 설명 |
|---|---|
--> | 화살표가 있는 실선 |
--- | 화살표 없는 실선 |
-.- | 화살표 없는 점선 |
-.-> | 화살표가 있는 점선 |
==> | 굵은 화살표 |
연결선에 텍스트 추가
실제 예시: 로그인 프로세스
서브그래프
관련 노드를 그룹화하여 가독성을 높입니다:
서브그래프 내에서 별도의 방향을 지정할 수 있습니다:
주의: 서브그래프 내부의 노드가 외부 노드와 직접 연결되면, 해당 서브그래프의 direction 설정이 무시되고 상위 그래프의 방향을 따릅니다.
시퀀스 다이어그램 (Sequence Diagram)
객체 간의 상호작용을 시간 순서대로 표현합니다. API 호출 흐름이나 시스템 간 통신을 설명할 때 유용합니다.
기본 문법
메시지 타입
| 문법 | 설명 |
|---|---|
-> | 실선, 화살표 없음 |
--> | 점선, 화살표 없음 |
->> | 실선, 화살표 |
-->> | 점선, 화살표 |
-x | 실선, X 표시 (메시지 실패) |
--x | 점선, X 표시 |
-) | 실선, 열린 화살표 (비동기) |
--) | 점선, 열린 화살표 (비동기) |
활성화 표시
+와 -로 참여자의 활성 상태를 표시할 수 있습니다:
반복, 조건, 병렬 처리
| 키워드 | 설명 |
|---|---|
alt/else/end | 조건 분기 (if-else) |
opt/end | 선택적 실행 (if without else) |
loop/end | 반복 |
par/and/end | 병렬 실행 |
실제 예시: OAuth 2.0 인증 흐름
상태 다이어그램 (State Diagram)
시스템이나 객체의 상태 변화를 표현합니다. stateDiagram-v2를 사용합니다.
기본 문법
[*]: 시작 또는 종료 상태-->: 상태 전이: 텍스트: 전이 조건/액션
복합 상태 (Composite State)
상태 안에 하위 상태를 포함할 수 있습니다:
Fork와 Join (병렬 처리)
실제 예시: 주문 상태
클래스 다이어그램 (Class Diagram)
객체지향 설계에서 클래스 간의 관계를 표현합니다.
기본 문법
접근 제어자
| 기호 | 의미 |
|---|---|
+ | public |
- | private |
# | protected |
~ | package/internal |
관계 타입
| 문법 | 관계 | 설명 |
|---|---|---|
<|-- | 상속 (Inheritance) | 부모-자식 관계 |
*-- | 컴포지션 (Composition) | 강한 소유 (생명주기 공유) |
o-- | 집합 (Aggregation) | 약한 소유 |
--> | 연관 (Association) | 일반적인 참조 관계 |
-- | 링크 (Link) | 단순 연결 |
..> | 의존 (Dependency) | 일시적 사용 |
..|> | 구현 (Realization) | 인터페이스 구현 |
다중성 표기
실제 예시: 쇼핑몰 도메인
파이 차트 (Pie Chart)
비율이나 분포를 시각화합니다.
실제 예시: 프로젝트 시간 배분
간트 차트 (Gantt Chart)
프로젝트 일정과 진행 상황을 표현합니다.
기본 문법
작업 상태
| 상태 | 설명 |
|---|---|
done | 완료된 작업 |
active | 진행 중인 작업 |
crit | 중요/긴급 작업 |
milestone | 마일스톤 (기간 0d) |
마인드맵 (Mindmap)
아이디어나 개념을 계층적으로 정리합니다. 들여쓰기로 계층을 표현합니다.
기본 문법
노드 모양
| 문법 | 모양 |
|---|---|
id | 기본 (사각형) |
id[텍스트] | 사각형 |
id(텍스트) | 둥근 사각형 |
id((텍스트)) | 원형 |
아이콘 추가
아이콘은 Font Awesome이나 Material Design Icons를 사용할 수 있습니다 (사이트에서 지원하는 경우):
실제 예시: 학습 로드맵
자주 사용하는 패턴
API 엔드포인트 문서화
에러 처리 흐름
데이터 파이프라인
스타일 커스터마이징
노드 스타일 지정
링크 스타일 지정
주의사항
- 특수문자 처리: 괄호, 따옴표 등 특수문자는 텍스트를 따옴표로 감싸세요.
- 노드 ID: 공백 없이 영문, 숫자, 언더스코어 사용을 권장합니다.
- 플랫폼 차이: GitHub, GitLab, Notion 등 플랫폼마다 지원하는 Mermaid 버전이 달라 일부 기능이 동작하지 않을 수 있습니다.
- 키워드:
flowchart는 v8.0+,stateDiagram-v2는 v8.6+ 에서 지원됩니다.
참고 자료
- Mermaid 공식 문서
- Mermaid Live Editor - 실시간으로 다이어그램을 테스트할 수 있는 온라인 에디터
- Mermaid GitHub
Mermaid를 활용하면 문서에 다이어그램을 쉽게 추가할 수 있고, 코드와 함께 버전 관리가 가능해집니다. 처음에는 문법이 낯설 수 있지만, 자주 사용하는 패턴 몇 가지만 익히면 문서 작성 생산성이 크게 향상됩니다.