Mermaid 다이어그램 가이드 Part 1: Flowchart 기본
이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.
Mermaid란?#
Mermaid는 마크다운 스타일의 텍스트로 다이어그램을 생성하는 JavaScript 기반 도구입니다. 별도의 드로잉 도구 없이도 Git에서 버전 관리가 가능한 다이어그램을 작성할 수 있어, 개발 문서화에 특히 유용합니다.
GitHub, GitLab, Notion, Obsidian 등 다양한 플랫폼에서 기본 지원되며, VS Code 확장 프로그램을 통해 실시간 미리보기도 가능합니다.
Flowchart 기본 문법#
Flowchart는 프로세스의 흐름을 시각화하는 가장 기본적인 다이어그램입니다. 노드(Node)와 엣지(Edge)로 구성됩니다.
다이어그램 선언#
flowchart TD
A --> B
flowchart TD
A --> B
flowchart 키워드로 시작하며, 바로 뒤에 방향을 지정합니다. graph 키워드도 사용 가능하지만 flowchart가 더 많은 기능을 지원합니다.
방향(Direction) 설정#
| 방향 | 설명 | 영문 풀네임 |
|---|---|---|
TB | 위에서 아래로 | Top to Bottom |
TD | 위에서 아래로 (TB와 동일) | Top Down |
BT | 아래에서 위로 | Bottom to Top |
LR | 왼쪽에서 오른쪽으로 | Left to Right |
RL | 오른쪽에서 왼쪽으로 | Right to Left |
flowchart LR
시작 --> 처리 --> 종료
flowchart LR
시작 --> 처리 --> 종료
flowchart TB
시작 --> 처리 --> 종료
flowchart TB
시작 --> 처리 --> 종료
노드(Node) 정의#
기본 노드#
가장 단순한 형태로, ID만 지정하면 ID가 곧 노드에 표시되는 텍스트가 됩니다.
flowchart LR
NodeA
flowchart LR
NodeA
텍스트가 있는 노드#
ID와 표시 텍스트를 분리할 수 있습니다. 같은 노드를 여러 번 참조할 때 ID를 짧게 유지하면서 긴 텍스트를 표시할 수 있어 유용합니다.
flowchart LR
id1[사각형 노드]
id2(둥근 모서리 노드)
id3([스타디움 형태])
id4[[서브루틴]]
id5[(데이터베이스)]
id6((원형))
flowchart LR
id1[사각형 노드]
id2(둥근 모서리 노드)
id3([스타디움 형태])
id4[[서브루틴]]
id5[(데이터베이스)]
id6((원형))
노드 모양 총정리#
| 문법 | 모양 | 용도 |
|---|---|---|
A[텍스트] | 사각형 | 일반 프로세스 |
A(텍스트) | 둥근 모서리 | 시작/종료 |
A([텍스트]) | 스타디움 | 터미널 |
A[[텍스트]] | 서브루틴 | 서브프로세스 |
A[(텍스트)] | 실린더 | 데이터베이스 |
A((텍스트)) | 원형 | 연결점 |
A{텍스트} | 다이아몬드 | 조건/분기 |
A{{텍스트}} | 육각형 | 준비 단계 |
A[/텍스트/] | 평행사변형 | 입력 |
A[\텍스트\] | 역 평행사변형 | 출력 |
A[/텍스트\] | 사다리꼴 | 수동 작업 |
A[\텍스트/] | 역 사다리꼴 | 수동 조작 |
A>텍스트] | 비대칭 | 오프페이지 참조 |
A(((텍스트))) | 이중 원 | 종료 상태 |
예제: 다양한 노드 형태 활용#
flowchart TD
A([시작]) --> B[프로세스 실행]
B --> C{조건 확인}
C -->|Yes| D[(DB 저장)]
C -->|No| E[/에러 출력/]
D --> F([종료])
E --> F
flowchart TD
A([시작]) --> B[프로세스 실행]
B --> C{조건 확인}
C -->|Yes| D[(DB 저장)]
C -->|No| E[/에러 출력/]
D --> F([종료])
E --> F
v11.3.0+ 새로운 Shape 문법#
Mermaid v11.3.0부터는 더 명시적인 shape 정의 문법을 지원합니다.
flowchart LR
A@{ shape: rect, label: "사각형" }
B@{ shape: diamond, label: "다이아몬드" }
C@{ shape: circle, label: "원" }
D@{ shape: cyl, label: "실린더" }
flowchart LR
A@{ shape: rect, label: "사각형" }
B@{ shape: diamond, label: "다이아몬드" }
C@{ shape: circle, label: "원" }
D@{ shape: cyl, label: "실린더" }
주요 shape 이름:
| Shape Name | 설명 | 별칭 |
|---|---|---|
rect | 사각형 | process, proc |
rounded | 둥근 모서리 | event |
stadium | 스타디움 | terminal, pill |
diamond | 다이아몬드 | decision, question |
cyl | 실린더 | database, db |
circle | 원 | circ |
hex | 육각형 | hexagon, prepare |
doc | 문서 | document |
docs | 다중 문서 | documents |
fork | 포크/조인 | join |
엣지(Edge) - 연결선#
노드 간의 연결을 나타내며, 다양한 스타일을 지원합니다.
기본 연결 유형#
flowchart LR
A --> B
C --- D
E -.-> F
G ==> H
flowchart LR
A --> B
C --- D
E -.-> F
G ==> H
| 문법 | 설명 |
|---|---|
--> | 화살표가 있는 실선 |
--- | 화살표가 없는 실선 |
-.-> | 화살표가 있는 점선 |
-.- | 화살표가 없는 점선 |
==> | 화살표가 있는 굵은 선 |
=== | 화살표가 없는 굵은 선 |
텍스트가 있는 연결선#
flowchart LR
A -->|텍스트| B
C -- 텍스트 --> D
E -.텍스트.-> F
G ==텍스트==> H
flowchart LR
A -->|텍스트| B
C -- 텍스트 --> D
E -.텍스트.-> F
G ==텍스트==> H
두 가지 문법 모두 동일하게 동작합니다:
A -->|텍스트| BA -- 텍스트 --> B
특수 화살표#
flowchart LR
A --o B
C --x D
E o--o F
G <--> H
I x--x J
flowchart LR
A --o B
C --x D
E o--o F
G <--> H
I x--x J
| 문법 | 설명 |
|---|---|
--o | 원형 끝 |
--x | X 표시 끝 |
o--o | 양쪽 원형 |
<--> | 양방향 화살표 |
x--x | 양쪽 X 표시 |
연결선 길이 조절#
대시(-)를 추가하여 연결선의 최소 길이를 늘릴 수 있습니다.
flowchart TD
A --> B
A ---> C
A ----> D
flowchart TD
A --> B
A ---> C
A ----> D
| 길이 | 일반 | 화살표 | 굵은 선 | 점선 |
|---|---|---|---|---|
| 1 (기본) | --- | --> | === | -.- |
| 2 | ---- | ---> | ==== | -..- |
| 3 | ----- | ----> | ===== | -...- |
체이닝(Chaining)#
여러 연결을 한 줄에 작성할 수 있습니다.
flowchart LR
A --> B --> C --> D
E --> F & G --> H
flowchart LR
A --> B --> C --> D
E --> F & G --> H
& 연산자를 사용하면 여러 노드를 동시에 연결할 수 있습니다.
flowchart TD
A --> B & C & D --> E
flowchart TD
A --> B & C & D --> E
위 코드는 아래와 동일합니다:
flowchart TD
A --> B
A --> C
A --> D
B --> E
C --> E
D --> E
flowchart TD
A --> B
A --> C
A --> D
B --> E
C --> E
D --> E
실전 예제: API 요청 처리 흐름#
flowchart TD
A([클라이언트 요청]) --> B{인증 확인}
B -->|성공| C[권한 검증]
B -->|실패| D[/401 Unauthorized/]
C -->|허용| E[(데이터베이스 조회)]
C -->|거부| F[/403 Forbidden/]
E --> G{데이터 존재?}
G -->|Yes| H[200 OK + 데이터]
G -->|No| I[/404 Not Found/]
D --> J([응답 반환])
F --> J
H --> J
I --> J
flowchart TD
A([클라이언트 요청]) --> B{인증 확인}
B -->|성공| C[권한 검증]
B -->|실패| D[/401 Unauthorized/]
C -->|허용| E[(데이터베이스 조회)]
C -->|거부| F[/403 Forbidden/]
E --> G{데이터 존재?}
G -->|Yes| H[200 OK + 데이터]
G -->|No| I[/404 Not Found/]
D --> J([응답 반환])
F --> J
H --> J
I --> J
마크다운 텍스트 지원#
노드 내에서 마크다운 서식을 사용할 수 있습니다. 큰따옴표와 백틱을 함께 사용합니다.
flowchart LR
A["`**굵은 텍스트**
일반 텍스트
*이탤릭*`"]
B["`코드: **Redis**
포트: *6379*`"]
A --> B
flowchart LR
A["`**굵은 텍스트**
일반 텍스트
*이탤릭*`"]
B["`코드: **Redis**
포트: *6379*`"]
A --> B
주석(Comments)#
%%로 시작하는 줄은 주석으로 처리되어 렌더링되지 않습니다.
flowchart LR
%% 이것은 주석입니다
A --> B
%% B에서 C로의 연결
B --> C
flowchart LR
%% 이것은 주석입니다
A --> B
%% B에서 C로의 연결
B --> C
특수 문자 처리#
특수 문자가 포함된 텍스트는 따옴표로 감싸거나 HTML 엔티티를 사용합니다.
flowchart LR
A["따옴표가 필요한 텍스트 (괄호)"]
B["화살표 텍스트: A -> B"]
C["#35; 해시 기호"]
flowchart LR
A["따옴표가 필요한 텍스트 (괄호)"]
B["화살표 텍스트: A -> B"]
C["#35; 해시 기호"]
| 문자 | 엔티티 코드 |
|---|---|
# | #35; |
; | #59; |
& | #38; |
유니코드 텍스트#
한글, 일본어, 이모지 등 유니코드 텍스트는 큰따옴표로 감싸면 됩니다.
flowchart LR
A["시작 🚀"] --> B["처리 중..."]
B --> C["완료 ✅"]
flowchart LR
A["시작 🚀"] --> B["처리 중..."]
B --> C["완료 ✅"]
Read other posts