Mermaid 문법 치트시트

가장 짧게 작동하는 다이어그램

순서도는 선언 한 줄과 화살표 한 개만 있으면 됩니다. TD는 위에서 아래를 뜻하고, 폭이 넓은 프로세스에 더 어울리는 좌우 방향은 LR을 씁니다.

flowchart TD
  A[Start] --> B{Ready?}
  B -->|Yes| C[Ship it]
  B -->|No| A

A, B, C는 노드 id — 내부용 이름일 뿐 화면에는 그려지지 않습니다. 대괄호 안 텍스트가 라벨이며, 대괄호 스타일이 모양을 결정합니다.

노드 모양

모양은 라벨을 감싸는 구분 기호 쌍으로 정해집니다. 기억해둘 만한 것들은 다음과 같습니다:

💡라벨에 대괄호, 콜론, 따옴표가 들어가면 따옴표로 감싸세요: A["Load (raw) data"]. 따옴표가 없으면 파서가 문장부호를 문법으로 해석합니다.

화살표

화살표 길이도 의미가 있습니다. -->는 한 단계(rank)를 나타내고, --->는 대상을 한 단계 더 아래로 밀어냅니다. mermaid가 제공하는 레이아웃 제어 중 가장 단순한 방법입니다.

서브그래프로 그룹화하기

subgraph는 노드들 주위에 라벨이 붙은 상자를 그립니다. 서브그래프는 중첩할 수 있고, 화살표는 그 경계를 자유롭게 넘나들 수 있습니다.

flowchart LR
  subgraph api["API"]
    H[Handler] --> S[(Postgres)]
  end
  subgraph worker["Worker"]
    Q[Queue] --> W[Job]
  end
  H --> Q

색상과 스타일링

style은 노드 하나를 칠합니다. classDef와 class를 함께 쓰면 여러 노드를 한 번에 칠할 수 있는데, 노드가 서너 개를 넘어가면 이 방법이 필요해집니다.

flowchart TD
  A[OK] --> B[Failed]
  style A fill:#16a34a,stroke:#333,color:#fff
  classDef bad fill:#dc2626,stroke:#333,color:#fff
  class B bad

색상은 다이어그램 소스의 일부이므로 내보내기 후에도 유지되고 파일과 함께 이동합니다. 여기서는 렌더링 도구의 테마 설정에 의존하는 부분이 전혀 없습니다.

다이어그램 유형별 예제 하나씩

시퀀스 다이어그램

sequenceDiagram
  participant User
  participant API
  participant DB
  User->>API: request
  API->>DB: query
  DB-->>API: rows
  API-->>User: response

클래스 다이어그램

classDiagram
  class Animal {
    +String name
    +move()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

상태 다이어그램

stateDiagram-v2
  [*] --> Idle
  Idle --> Running: start
  Running --> Idle: stop
  Running --> [*]: finish

개체-관계 다이어그램

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    string email
  }

간트 차트

gantt
  title Project
  dateFormat YYYY-MM-DD
  section Phase 1
  Task 1 :a1, 2026-01-01, 5d
  Task 2 :after a1, 5d

mermaid가 자체적으로 렌더링되는 곳

• GitHub — 이슈, 풀 리퀘스트, 댓글, README 파일에서 펜스 처리된 ```mermaid 블록이 렌더링됩니다.
• GitLab — 같은 방식의 펜스 블록이 이슈, 머지 리퀘스트, 위키에서 렌더링됩니다.
• Notion — 언어를 Mermaid로 설정한 코드 블록이 소스 옆에 렌더링됩니다.
• Obsidian — 미리보기 모드에서 펜스 처리된 mermaid 블록이 렌더링됩니다.
• 문서 사이트 — Docusaurus, MkDocs Material, VitePress 모두 mermaid 블록을 지원합니다.

다이어그램을 이미지가 아니라 mermaid로 유지하는 진짜 이유가 여기 있습니다. 다이어그램이 그것을 설명하는 대상과 같은 텍스트 파일 안에 살아있으므로, 코드 리뷰에서 무엇이 바뀌었는지 그대로 볼 수 있습니다.