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 키워드로 시작하며, 바로 뒤에 방향을 지정합니다. 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 TB
    시작 --> 처리 --> 종료

노드(Node) 정의#

기본 노드#

가장 단순한 형태로, ID만 지정하면 ID가 곧 노드에 표시되는 텍스트가 됩니다.

flowchart LR
    NodeA

텍스트가 있는 노드#

ID와 표시 텍스트를 분리할 수 있습니다. 같은 노드를 여러 번 참조할 때 ID를 짧게 유지하면서 긴 텍스트를 표시할 수 있어 유용합니다.

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

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: "실린더" }

주요 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

두 가지 문법 모두 동일하게 동작합니다:

A -->|텍스트| B
A -- 텍스트 --> B

특수 화살표#

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

길이	일반	화살표	굵은 선	점선
1 (기본)	`---`	`-->`	`===`	`-.-`
2	`----`	`--->`	`====`	`-..-`
3	`-----`	`---->`	`=====`	`-...-`

체이닝(Chaining)#

여러 연결을 한 줄에 작성할 수 있습니다.

flowchart LR
    A --> B --> C --> D
    E --> F & G --> H

& 연산자를 사용하면 여러 노드를 동시에 연결할 수 있습니다.

flowchart TD
    A --> B & C & 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 LR
    A["`**굵은 텍스트**
    일반 텍스트
    *이탤릭*`"]
    B["`코드: **Redis**
    포트: *6379*`"]
    A --> B

주석(Comments)#

%%로 시작하는 줄은 주석으로 처리되어 렌더링되지 않습니다.

flowchart LR
    %% 이것은 주석입니다
    A --> B
    %% B에서 C로의 연결
    B --> C

특수 문자 처리#

특수 문자가 포함된 텍스트는 따옴표로 감싸거나 HTML 엔티티를 사용합니다.

flowchart LR
    A["따옴표가 필요한 텍스트 (괄호)"]
    B["화살표 텍스트: A -> B"]
    C["#35; 해시 기호"]

문자	엔티티 코드
`#`	`#35;`
`;`	`#59;`
`&`	`#38;`

유니코드 텍스트#

한글, 일본어, 이모지 등 유니코드 텍스트는 큰따옴표로 감싸면 됩니다.

flowchart LR
    A["시작 🚀"] --> B["처리 중..."]
    B --> C["완료 ✅"]