마크다운에서 Mermaid 다이어그램 그리기: 순서도, 시퀀스 다이어그램 등

다이어그램은 프로세스, 아키텍처, 일정을 긴 글보다 훨씬 잘 설명합니다. 하지만 그래픽 편집기로 그리면 이미지를 내보내고, 문서 옆에 보관하고, 무언가 바뀔 때마다 전부 다시 그려야 합니다.

Mermaid가 이 문제를 해결합니다. 마크다운 파일 안에 몇 줄의 텍스트로 다이어그램을 설명하면 미리 보기 도구가 그려 줍니다. 다이어그램이 같은 파일 안에 있으니 diff에도 나타나고, 문장을 고치듯 쉽게 수정할 수 있습니다. GitHub, GitLab, Obsidian, 여러 문서 생성기, 그리고 Markdown Preview Editor가 Mermaid를 기본으로 렌더링합니다.

Mermaid 다이어그램 넣는 법

코드 블록을 만들고 언어를 mermaid로 지정하세요.

markdown```mermaid
flowchart LR
  A[작성] --> B[미리 보기]
  B --> C{완성?}
  C -- 예 --> D[내보내기]
  C -- 아니요 --> A
```

미리 보기 도구는 이것을 다음과 같이 그립니다.

첫 줄은 다이어그램 종류를 지정합니다. 그 뒤의 모든 내용은 노드와 연결을 설명합니다.

순서도(플로우차트)

순서도는 가장 많이 쓰이는 다이어그램입니다. 방향은 키워드 뒤에 씁니다: TD 또는 TB(위에서 아래로), BT, LR(왼쪽에서 오른쪽으로), RL.

mermaidflowchart TD
  start([시작]) --> input[/파일 읽기/]
  input --> valid{올바른가?}
  valid -- 예 --> save[(데이터베이스에 저장)]
  valid -- 아니요 --> error[오류 표시]
  error --> input

레이블을 감싼 괄호가 노드 모양을 결정합니다.

연결: -->는 화살표, ---는 화살표 없는 선, -.->는 점선 화살표, ==>는 굵은 화살표입니다. 레이블은 -- text --> 또는 -->|text|로 붙입니다.

관련된 노드는 subgraph로 묶습니다.

mermaidflowchart LR
  subgraph Browser
    editor[편집기] --> preview[미리 보기]
  end
  preview --> export[HTML / PDF]

시퀀스 다이어그램

시퀀스 다이어그램은 참여자들이 시간 순서대로 메시지를 주고받는 과정을 보여 줍니다. API, 인증 흐름, 사용자 여정을 설명하기에 좋습니다.

mermaidsequenceDiagram
  participant U as 사용자
  participant A as 앱
  participant S as 서버
  U->>A: "로그인" 클릭
  A->>S: POST /login
  S-->>A: 200 OK + 토큰
  A-->>U: 대시보드 표시
  Note over A,S: 토큰은 1시간 후 만료됩니다

->>는 실선 화살표(요청), -->>는 점선 화살표(응답)입니다. Note over, Note left of, Note right of로 설명을 붙입니다. 반복과 분기는 loop, alt/else, opt 블록으로 나타냅니다.

간트 차트

간트 차트는 작업 목록을 타임라인으로 바꿔 줍니다. 작업은 특정 날짜에 시작하거나 다른 작업 after(이후)에 시작할 수 있습니다.

mermaidgantt
  title 문서화 스프린트
  dateFormat YYYY-MM-DD
  section 작성
  개요 작성    :done,   a1, 2026-10-01, 2d
  초안         :active, a2, after a1, 4d
  section 검토
  동료 검토    :        a3, after a2, 3d
  게시         :milestone, after a3, 0d

상태 다이어그램

상태 다이어그램은 주문, 문서, UI 컴포넌트처럼 무언가가 상태 사이를 어떻게 오가는지 설명합니다.

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : 제출
  Review --> Draft : 수정 요청
  Review --> Published : 승인
  Published --> [*]

파이 차트

전체 대비 비율을 빠르게 보여 줄 때는 조각마다 한 줄씩 쓰는 파이 차트를 쓰세요.

mermaidpie title 문서 작업 시간은 어디에 쓰일까
  "작성" : 45
  "서식 정리" : 15
  "다이어그램 최신 상태 유지" : 40

Mermaid는 클래스 다이어그램, ER 다이어그램(개체-관계 다이어그램), 마인드맵, 타임라인, Git 그래프, 사분면 차트 등도 지원합니다. 각 문법은 Mermaid 공식 웹사이트에 설명되어 있습니다.

읽기 쉬운 다이어그램을 위한 팁

• 작게 유지하세요. 노드가 15~20개를 넘으면 읽기 어려워집니다. 아이디어 하나당 다이어그램 하나로 나누세요.
• 방향을 신중하게 고르세요. LR은 단계가 적은 프로세스에, TD는 계층 구조와 긴 흐름에 어울리며, 특히 좁은 화면에서 좋습니다.
• 짧은 ID와 읽기 쉬운 레이블을 쓰세요. 레이블을 그대로 ID로 쓰지 말고 auth[Check the session]처럼 쓰면 연결 코드가 짧아집니다.
• 특수 문자가 있는 레이블은 따옴표로 감싸세요: A["Price: $5 (incl. tax)"].
• 줄 앞에 %%를 붙여 주석을 다세요. 그릴 때는 무시됩니다.
• 입력하면서 미리 보세요. 화살표나 괄호 하나만 빠져도 다이어그램 전체가 깨지므로, 실시간 미리 보기가 있으면 추측할 일이 크게 줄어듭니다. Markdown Preview Editor에서는 편집하는 동안 다이어그램이 다시 그려지며, 고급 편집기 도구 모음의 Mermaid 다이어그램 버튼으로 기본 템플릿을 넣을 수 있습니다.

다이어그램이 있는 문서 공유하기

문서를 HTML이나 PDF로 내보내면 다이어그램이 이미지로 포함되므로, 읽는 사람이 Mermaid를 설치할 필요가 없습니다. 다이어그램과 함께 수식을 쓰려면 마크다운에서 수식 쓰는 법을, 표, 할 일 목록, 알림 상자 등 나머지는 마크다운 문법 총정리를 곁에 두고 참고하세요.