보고서에 순서도 하나 넣으려고 파워포인트를 여는 경험, 누구나 한 번쯤 해보셨을 겁니다. 네모 하나 그리고, 화살표 연결하고, 위치 미세 조정하다 보면 어느새 30분이 지나 있죠. 좀 더 전문적인 다이어그램이 필요하면 Draw.io나 Lucidchart를 열지만, 결국 이미지 파일로 내보내서 문서에 붙여넣는 과정이 번거롭기는 마찬가지입니다. 다이어그램 내용이 바뀌면 원본 파일을 찾아서 수정하고 다시 내보내야 하니, 문서 유지보수는 더 골치 아파집니다.

그런데 만약 마크다운 안에 텍스트 몇 줄만 쓰면 다이어그램이 자동으로 그려진다면 어떨까요? 수정할 때도 텍스트만 고치면 즉시 반영되고, Git으로 버전 관리까지 가능하다면요. 이것이 바로 Mermaid가 하는 일입니다. 2026년 현재, GitHub·Notion·Obsidian·VS Code 등 개발자와 지식 노동자가 매일 쓰는 도구 대부분이 Mermaid를 기본 지원합니다. 한번 문법을 익혀두면 별도의 그림 도구 없이도 전문적인 다이어그램을 순식간에 만들 수 있습니다.

이 글에서는 Mermaid의 핵심 다이어그램 유형을 실전 예제와 함께 총정리합니다. 순서도, 시퀀스 다이어그램, ER 다이어그램, 간트 차트는 물론이고 마인드맵과 파이 차트까지, 자주 쓰는 문법을 코드와 함께 하나씩 살펴보겠습니다.

Mermaid란 무엇인가 — 텍스트로 그림을 그리는 오픈소스 라이브러리

Mermaid는 2014년 Knut Sveidqvist가 만든 JavaScript 기반 오픈소스 다이어그램 렌더링 라이브러리입니다. 사용자가 정해진 텍스트 문법으로 다이어그램 구조를 기술하면, 브라우저가 이를 파싱하여 SVG 이미지로 변환해 화면에 보여줍니다. 핵심은 단 하나, 그림을 마우스로 그리지 않고 코드로 작성한다는 것입니다.

이 접근 방식이 가져오는 실질적인 이점은 세 가지입니다.

• 버전 관리: 다이어그램이 텍스트이므로 Git diff로 변경 이력을 추적할 수 있습니다. 바이너리 이미지 파일과 달리, 누가 어떤 노드를 추가하거나 화살표를 바꿨는지 한눈에 보입니다.
• 도구 종속 없음: Visio 라이선스도, Figma 계정도 필요 없습니다. 텍스트 에디터만 있으면 어디서든 다이어그램을 편집할 수 있고, 지원 플랫폼에서 바로 렌더링됩니다.
• 문서와의 일체화: 다이어그램이 문서 파일 안에 텍스트로 존재하므로, 별도의 이미지 파일을 관리하거나 링크가 깨질 걱정이 없습니다. 문서를 수정할 때 다이어그램도 같은 파일 안에서 바로 고칩니다.

2022년 GitHub가 마크다운에서 Mermaid 코드 블록을 네이티브로 렌더링하기 시작한 것이 대중화의 결정적 계기였습니다. 이후 GitLab, Notion, Obsidian, Confluence, Typora, Docusaurus 등 주요 문서 도구들이 잇따라 지원을 추가했고, 2026년 현재 Mermaid는 사실상 마크다운 생태계의 표준 다이어그램 문법으로 자리 잡았습니다.

바로 시작하기 — Mermaid를 사용할 수 있는 환경

Mermaid를 사용하기 위해 별도의 프로그램을 설치할 필요가 거의 없습니다. 이미 사용 중인 도구에서 바로 시작할 수 있습니다.

Mermaid Live Editor — 가장 빠른 실습 환경

Mermaid 공식 온라인 에디터(mermaid.live)에서 왼쪽에 코드를 입력하면 오른쪽에 다이어그램이 실시간으로 렌더링됩니다. 별도의 설치나 로그인 없이 브라우저만 열면 됩니다. 완성된 다이어그램은 SVG 또는 PNG로 내보내기할 수 있어, Mermaid를 지원하지 않는 환경에 이미지로 삽입할 때도 유용합니다. 이 글의 예제를 따라 하실 때 Live Editor를 옆에 열어두시면 가장 편리합니다.

GitHub — README와 이슈에 바로 삽입

GitHub의 마크다운 파일(.md), 이슈, PR 본문, 위키 어디서든 아래처럼 코드 블록 언어를 mermaid로 지정하면 자동 렌더링됩니다.

```mermaid
graph TD
    A[시작] --> B[끝]
```

README.md에 프로젝트 아키텍처 다이어그램을 넣을 때 이 방법만으로 충분합니다. 별도의 이미지 파일이 필요 없으니 리포지토리가 깔끔해집니다.

VS Code — 편집과 미리보기를 동시에

VS Code에서는 Markdown Preview Mermaid Support 확장을 설치하면 마크다운 미리보기 패널에서 Mermaid 다이어그램이 렌더링됩니다. 혹은 Mermaid Editor 확장을 사용하면 .mmd 파일을 직접 편집하면서 실시간 미리보기를 볼 수 있습니다.

Notion과 Obsidian

Notion은 코드 블록에서 언어를 Mermaid로 선택하면 바로 다이어그램이 표시됩니다. Obsidian도 동일하게 mermaid 코드 블록을 지원하며, 커뮤니티 플러그인을 통해 추가 기능을 확장할 수도 있습니다.

순서도(Flowchart) — 가장 많이 쓰는 기본 다이어그램

순서도는 Mermaid에서 가장 기본적이면서도 가장 자주 사용되는 다이어그램입니다. 업무 프로세스, 알고리즘 흐름, 의사결정 구조 등 거의 모든 논리적 흐름을 표현할 수 있습니다.

기본 구조와 방향

순서도는 graph 또는 flowchart 키워드로 시작하며, 바로 뒤에 방향을 지정합니다.

• TD 또는 TB: 위에서 아래로(Top to Bottom) — 가장 일반적
• LR: 왼쪽에서 오른쪽으로(Left to Right)
• BT: 아래에서 위로
• RL: 오른쪽에서 왼쪽으로

flowchart TD
    A[회원가입 페이지] --> B[정보 입력]
    B --> C{유효성 검사}
    C -->|통과| D[계정 생성]
    C -->|실패| E[에러 메시지]
    E --> B
    D --> F[환영 이메일 발송]
    F --> G[완료]

이 코드를 Mermaid가 렌더링하면, 회원가입 페이지에서 시작하여 정보를 입력하고, 유효성 검사를 거쳐 성공 또는 실패로 분기하는 깔끔한 순서도가 그려집니다. 실패 시 정보 입력 단계로 돌아가는 루프도 자연스럽게 표현됩니다.

노드 형태 — 모양으로 의미를 전달한다

Mermaid 순서도에서 노드의 형태는 괄호 기호로 결정됩니다. 형태마다 관례적인 의미가 있으므로 적절히 사용하면 다이어그램의 가독성이 크게 높아집니다.

• A[텍스트] — 사각형. 일반적인 처리 단계를 나타냅니다.
• B(텍스트) — 모서리가 둥근 사각형. 시작/종료 또는 부드러운 단계에 주로 사용합니다.
• C{텍스트} — 다이아몬드(마름모). 조건 분기, 의사결정을 나타냅니다.
• D((텍스트)) — 원형. 연결점이나 특수 상태를 표시합니다.
• E[/텍스트/] — 평행사변형. 입출력 데이터를 나타냅니다.
• F[[텍스트]] — 이중 테두리 사각형. 서브루틴이나 외부 프로세스를 나타냅니다.
• G>텍스트] — 비대칭 형태(깃발 모양). 특수 표기에 사용합니다.

예를 들어 조건 분기에는 반드시 다이아몬드 {}를 사용하고, 일반 처리에는 사각형 []을 쓰는 것이 표준적인 순서도 관례입니다. 이 관례를 지키면 다이어그램을 처음 보는 사람도 흐름을 직관적으로 파악할 수 있습니다.

연결선 종류 — 관계의 성격을 표현한다

노드 사이의 연결선도 여러 형태를 사용할 수 있습니다.

• A –> B — 실선 화살표. 일반적인 흐름을 나타냅니다.
• A — B — 화살표 없는 실선. 연관 관계만 표시합니다.
• A -..-> B — 점선 화살표. 선택적이거나 비동기적인 흐름에 사용합니다.
• A ==> B — 굵은 실선 화살표. 주요 흐름이나 강조할 경로에 씁니다.
• A –>|라벨| B — 연결선 위에 텍스트 라벨을 붙입니다. 조건이나 설명을 추가할 때 유용합니다.

서브그래프 — 영역을 나누어 복잡도 관리하기

다이어그램이 복잡해지면 관련 노드를 그룹으로 묶어 시각적으로 구분해야 합니다. Mermaid에서는 subgraph 키워드로 이를 구현합니다.

flowchart TD
    subgraph 프론트엔드
        A[사용자 입력] --> B[폼 검증]
    end
    subgraph 백엔드
        C[API 처리] --> D[DB 저장]
    end
    B --> C

이 코드를 렌더링하면 프론트엔드와 백엔드가 각각 박스로 구분되고, 두 영역 사이의 연결이 명확하게 보입니다. 시스템 아키텍처를 설명할 때 서브그래프를 활용하면 한 장의 다이어그램으로도 전체 구조를 체계적으로 전달할 수 있습니다.

시퀀스 다이어그램 — 시스템 간 대화를 시간순으로 그린다

시퀀스 다이어그램은 여러 구성요소 사이의 메시지 교환을 시간 순서대로 보여주는 다이어그램입니다. API 호출 흐름, 마이크로서비스 간 통신, 사용자와 시스템 사이의 상호작용을 설명할 때 가장 효과적인 도구입니다.

기본 구조

sequenceDiagram
    participant 사용자
    participant 서버
    participant DB

    사용자->>서버: 로그인 요청
    서버->>DB: 사용자 조회
    DB-->>서버: 사용자 정보
    서버-->>사용자: 인증 토큰

이 코드는 사용자가 서버에 로그인 요청을 보내고, 서버가 DB에서 사용자를 조회하여 결과를 돌려받은 뒤, 최종적으로 사용자에게 인증 토큰을 응답하는 과정을 한눈에 보여줍니다.

메시지 유형과 활성화

화살표 종류로 메시지의 성격을 구분합니다.

• ->> — 실선 화살표. 동기 요청(호출)을 나타냅니다.
• –>> — 점선 화살표. 응답이나 비동기 반환을 나타냅니다.
• -)) — 비동기 메시지(이벤트 발행 등)를 나타냅니다.

참여자가 처리 중인 구간을 강조하려면 activate와 deactivate를 사용합니다.

sequenceDiagram
    사용자->>서버: 주문 요청
    activate 서버
    서버->>결제: 결제 처리
    activate 결제
    결제-->>서버: 결제 완료
    deactivate 결제
    서버-->>사용자: 주문 확인
    deactivate 서버

활성화 구간이 표시되면 각 참여자가 언제 바쁘게 일하고 있는지 시각적으로 즉시 파악됩니다. 시스템의 병목이 어디인지 찾을 때도 유용합니다.

조건 분기와 반복

시퀀스 다이어그램에서도 조건문과 반복을 표현할 수 있습니다.

sequenceDiagram
    사용자->>서버: 로그인 요청
    alt 비밀번호 일치
        서버-->>사용자: 로그인 성공
    else 비밀번호 불일치
        서버-->>사용자: 로그인 실패
    end

    loop 매 5초
        사용자->>서버: 상태 확인
        서버-->>사용자: 현재 상태
    end

alt/else는 조건에 따라 다른 메시지가 오가는 분기를, loop는 반복적으로 발생하는 메시지 패턴을 표현합니다. 또한 Note over A,B: 텍스트 구문으로 참여자 위에 설명 노트를 달 수도 있습니다. 복잡한 비즈니스 로직도 이 세 가지 구문이면 충분히 표현 가능합니다.

실전 예제 — OAuth 인증 흐름

sequenceDiagram
    actor User
    participant App
    participant Auth as Auth Server
    participant API

    User->>App: Login with Google
    App->>Auth: Authorization Request
    Auth-->>User: Login Page
    User->>Auth: Credentials
    Auth-->>App: Authorization Code
    App->>Auth: Exchange Code for Token
    Auth-->>App: Access Token
    App->>API: Request with Token
    API-->>App: Protected Data
    App-->>User: Dashboard

이 다이어그램은 OAuth 인증의 전체 흐름을 일목요연하게 보여줍니다. 기술 문서나 팀 내 교육 자료에 이런 시퀀스 다이어그램 하나만 넣어도, 장문의 텍스트 설명보다 훨씬 빠르게 이해할 수 있습니다.

ER 다이어그램 — 데이터 관계를 설계하고 공유한다

엔티티 관계(Entity Relationship) 다이어그램은 데이터베이스 테이블 간의 관계를 시각화합니다. 새 프로젝트의 데이터 모델을 설계하거나, 기존 시스템의 테이블 구조를 문서화할 때 필수적인 도구입니다.

기본 문법

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "is in"

    CUSTOMER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int customer_id FK
        date created_at
        string status
    }
    PRODUCT {
        int id PK
        string name
        decimal price
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }

관계를 나타내는 기호가 처음에는 낯설 수 있지만, 규칙은 단순합니다.

• || — 정확히 하나(one, 필수)
• o| — 0 또는 하나(zero or one, 선택)
• |{ — 하나 이상(one or more)
• o{ — 0 이상(zero or more)

예를 들어 CUSTOMER ||--o{ ORDER는 “한 고객은 0개 이상의 주문을 가질 수 있고, 하나의 주문은 반드시 한 명의 고객에게 속한다”는 뜻입니다. 관계선 끝의 콜론 뒤에는 관계의 이름을 적어서 가독성을 높입니다.

각 엔티티 블록 안에 속성을 나열할 수 있으며, PK(Primary Key)와 FK(Foreign Key) 표기도 지원합니다. 이 한 장의 다이어그램으로 데이터 모델 논의가 훨씬 수월해집니다.

간트 차트 — 프로젝트 일정을 코드로 관리한다

간트 차트는 프로젝트의 작업별 일정과 진행 상황을 타임라인으로 보여주는 다이어그램입니다. Mermaid로 작성하면 일정이 변경될 때 텍스트만 수정하면 되므로, 별도의 프로젝트 관리 도구 없이도 간단한 일정 시각화가 가능합니다.

기본 문법

gantt
    title 블로그 리뉴얼 프로젝트
    dateFormat YYYY-MM-DD
    axisFormat %m/%d

    section 기획
        요구사항 정리     :done,    req, 2026-06-01, 3d
        와이어프레임 설계  :done,    wf,  after req,  2d

    section 디자인
        UI 디자인         :active,  ui,  after wf,   5d
        디자인 리뷰       :         rev, after ui,   1d

    section 개발
        프론트엔드 개발   :         fe,  after rev,  7d
        백엔드 API 개발   :         be,  after rev,  5d
        통합 테스트       :         test,after fe,   3d

    section 배포
        스테이징 배포     :         stg, after test, 1d
        프로덕션 배포     :crit,    prd, after stg,  1d

이 코드를 렌더링하면 기획-디자인-개발-배포의 네 단계가 타임라인 위에 깔끔하게 배치됩니다. 각 태스크의 상태는 키워드로 표시합니다.

• done: 완료된 작업. 다른 색상으로 채워집니다.
• active: 현재 진행 중인 작업.
• crit: 크리티컬 패스(핵심 경로) 작업. 빨간색으로 강조됩니다.

작업의 시작일은 절대 날짜로 지정하거나 after 태스크ID로 선행 작업 완료 후로 설정할 수 있고, 기간은 3d(3일) 형태로 씁니다. 팀 미팅에서 프로젝트 일정을 공유할 때 GitHub README에 이 간트 차트 하나만 넣어도 별도의 프로젝트 관리 도구 못지않은 가시성을 확보할 수 있습니다.

그 외 유용한 다이어그램 — 파이 차트, 마인드맵, 타임라인

Mermaid는 순서도·시퀀스·ER·간트 외에도 여러 다이어그램 유형을 지원합니다. 그중 실무에서 특히 유용한 세 가지를 소개합니다.

파이 차트(Pie Chart) — 비율을 한눈에

pie title 주간 업무 시간 분배
    "코딩" : 35
    "코드 리뷰" : 15
    "미팅" : 20
    "문서 작성" : 15
    "학습" : 15

보고서에 비율 데이터를 시각화할 때 가장 빠른 방법입니다. pie 키워드 다음에 항목과 값만 나열하면 됩니다. 복잡한 데이터 시각화에는 적합하지 않지만, 간단한 비율 표현에는 이보다 빠른 도구가 없습니다.

마인드맵(Mindmap) — 아이디어를 구조화한다

mindmap
  root((프로젝트 계획))
    기획
      시장 조사
      경쟁사 분석
      사용자 인터뷰
    설계
      시스템 아키텍처
      데이터 모델
      API 설계
    개발
      프론트엔드
        React
        TypeScript
      백엔드
        FastAPI
        PostgreSQL
    배포
      CI/CD
      모니터링

들여쓰기만으로 계층 구조가 결정되므로 문법이 매우 직관적입니다. 브레인스토밍 결과를 정리하거나 학습 내용을 구조화할 때 마크다운 문서 안에서 바로 마인드맵을 그릴 수 있으니 별도의 마인드맵 도구를 열 필요가 없습니다.

타임라인(Timeline) — 이정표를 시각화한다

timeline
    title 제품 출시 로드맵
    2026 Q1 : MVP 개발 완료
            : 내부 알파 테스트
    2026 Q2 : 클로즈드 베타 출시
            : 사용자 피드백 수집
    2026 Q3 : 퍼블릭 베타 오픈
            : 성능 최적화
    2026 Q4 : 정식 출시
            : 마케팅 캠페인

제품 로드맵, 프로젝트 마일스톤, 회사 연혁 같은 시간순 정보를 깔끔하게 표현합니다. 투자자 보고서나 팀 내부 공유 문서에 넣으면 텍스트 나열보다 훨씬 임팩트 있습니다.

Git 그래프 — 브랜치 전략을 그림으로 설명한다

gitgraph
    commit id: "init"
    branch feature/login
    commit id: "login-ui"
    commit id: "login-api"
    checkout main
    merge feature/login
    commit id: "hotfix"
    branch feature/dashboard
    commit id: "dashboard-v1"
    checkout main
    merge feature/dashboard

Git 브랜치 전략(GitFlow, GitHub Flow 등)을 설명하는 기술 문서에 이 다이어그램을 넣으면 복잡한 브랜치 흐름도 직관적으로 이해시킬 수 있습니다.

실전 활용 팁과 자주 하는 실수

문법을 알았으니 이제 실전에서 효과적으로 활용하는 방법을 정리합니다.

팁 1 — GitHub README에 아키텍처 다이어그램 넣기

오픈소스 프로젝트나 팀 리포지토리의 README에 시스템 아키텍처를 Mermaid로 넣으면, 새 팀원이 프로젝트 구조를 파악하는 시간이 크게 줄어듭니다. 별도의 이미지 파일 관리가 필요 없고, 아키텍처가 변경되면 README의 텍스트만 수정하면 됩니다.

flowchart LR
    Client --> Gateway
    Gateway --> API["API Server"]
    API --> DB[(PostgreSQL)]
    API --> Cache[(Redis)]
    API --> Queue["Message Queue"]

이 정도의 시스템 구성도를 그리는 데 30초도 걸리지 않습니다. Visio로 같은 다이어그램을 만들었다면 5분은 넘게 걸렸을 겁니다.

팁 2 — 복잡한 다이어그램은 분할하라

하나의 다이어그램에 노드를 20개 이상 넣으면 가독성이 급격히 떨어집니다. 복잡한 시스템은 여러 개의 작은 다이어그램으로 분할하는 것이 효과적입니다. 전체 시스템 개요는 순서도로, 특정 API 호출 흐름은 시퀀스 다이어그램으로, 데이터 구조는 ER 다이어그램으로 나누어 각각의 역할에 맞는 다이어그램 유형을 선택하세요.

팁 3 — 노드 ID와 표시 텍스트를 분리하라

flowchart TD
    auth["인증 서비스"]
    user_db[("사용자 DB")]
    auth --> user_db

노드 ID를 짧은 영문으로 두고 표시 텍스트를 따옴표 안에 한글로 쓰면, 코드의 가독성과 다이어그램의 표현력을 모두 잡을 수 있습니다. 나중에 노드 간 연결을 추가할 때도 짧은 ID로 참조하니 타이핑이 편합니다.

팁 4 — 테마와 스타일 커스터마이징

Mermaid는 기본 테마 외에도 dark, forest, neutral 등의 내장 테마를 제공합니다. 다이어그램 맨 위에 설정 블록을 추가하면 됩니다.

%%{init: {'theme': 'forest'}}%%
flowchart TD
    A[시작] --> B[처리] --> C[끝]

개별 노드의 색상을 바꾸려면 style 구문을 사용합니다.

flowchart TD
    A[정상] --> B[경고] --> C[오류]
    style A fill:#4ade80,color:#000
    style B fill:#facc15,color:#000
    style C fill:#f87171,color:#fff

상태별로 색상을 다르게 하면 다이어그램의 정보 전달력이 한층 높아집니다. 다만 색상을 너무 많이 쓰면 오히려 시각적 혼란을 주므로, 강조가 필요한 노드에만 제한적으로 사용하는 것을 권합니다.

팁 5 — AI 도구와 함께 사용하기

ChatGPT나 Claude 같은 AI 챗봇에게 “이 API 흐름을 Mermaid 시퀀스 다이어그램으로 그려줘”라고 요청하면 바로 코드를 생성해줍니다. 텍스트로 설명한 비즈니스 프로세스를 Mermaid 순서도로 변환해달라고 하는 것도 매우 효과적입니다. 생성된 코드를 Live Editor에 붙여넣고 미세 조정만 하면, 수동으로 처음부터 작성하는 것보다 훨씬 빠릅니다.

자주 하는 실수 5가지와 해결법

• 들여쓰기 불일치: 마인드맵처럼 들여쓰기가 구조를 결정하는 다이어그램에서 탭과 스페이스를 섞으면 렌더링 오류가 납니다. 스페이스로 통일하세요.
• 특수문자 미이스케이프: 노드 텍스트에 괄호 ()나 중괄호 {}가 포함되면 Mermaid가 문법 기호로 인식합니다. 텍스트를 큰따옴표 ""로 감싸면 해결됩니다.
• 세미콜론 누락: 시퀀스 다이어그램에서 Note over 구문 뒤에 콜론을 빠뜨리면 전체가 렌더링되지 않습니다. 에러 메시지를 확인하고 콜론 위치를 점검하세요.
• 노드 ID 중복: 같은 ID를 다른 텍스트로 두 번 선언하면 첫 번째 텍스트만 표시됩니다. 고유한 ID를 부여하세요.
• 한글 노드 ID: 일부 환경에서 노드 ID에 한글을 직접 쓰면 인코딩 문제가 발생할 수 있습니다. ID는 영문, 표시 텍스트는 한글로 분리하는 것이 안전합니다.

요약 — Mermaid 다이어그램 유형별 한눈에 보기

지금까지 살펴본 Mermaid 다이어그램 유형을 정리하면 다음과 같습니다.

• 순서도(flowchart): 프로세스 흐름, 알고리즘, 의사결정 로직
• 시퀀스(sequenceDiagram): 시스템 간 메시지 교환, API 호출 순서
• ER(erDiagram): 데이터베이스 테이블 관계, 데이터 모델 설계
• 간트(gantt): 프로젝트 일정, 작업 진행 상황
• 파이(pie): 비율, 분포, 통계 데이터
• 마인드맵(mindmap): 아이디어 구조화, 학습 정리
• 타임라인(timeline): 이정표, 연혁, 로드맵
• Git 그래프(gitgraph): 브랜치 전략, 병합 흐름

이 외에도 클래스 다이어그램(classDiagram), 상태 다이어그램(stateDiagram-v2), C4 아키텍처 다이어그램, 사분면 차트(quadrantChart), XY 차트(xychart-beta) 등 Mermaid는 계속해서 새로운 다이어그램 유형을 추가하고 있습니다. 공식 문서(mermaid.js.org)에서 전체 목록과 최신 업데이트를 확인할 수 있습니다.

마무리 — 다이어그램도 코드처럼 관리하는 시대

Mermaid를 처음 접하면 “이걸 텍스트로 써야 해?”라는 의문이 들 수 있습니다. 마우스로 네모를 그리는 것이 더 직관적이지 않냐는 생각도 당연합니다. 하지만 다이어그램을 한두 번 만들고 끝이 아니라 지속적으로 업데이트해야 하는 문서라면, 텍스트 기반 접근의 장점은 압도적입니다.

코드 리뷰에서 다이어그램 변경 사항을 diff로 확인하고, PR 코멘트에서 다이어그램을 바로 그려 설명하고, 기술 블로그에 별도의 이미지 관리 없이 다이어그램을 삽입하는 경험은 한번 해보면 이전으로 돌아가기 어렵습니다.

시작은 간단합니다. 지금 작성 중인 문서에 마크다운 코드 블록을 열고 flowchart TD를 입력해보세요. 노드 두 개를 화살표로 연결하는 순간, “아, 이렇게 쉬운 거였어?”라는 감탄이 나올 겁니다. 복잡한 문법을 한꺼번에 외울 필요 없습니다. 순서도 하나에서 시작해 필요할 때마다 새로운 다이어그램 유형을 하나씩 추가해가면 됩니다. 이 글이 그 첫 번째 순서도를 그리는 계기가 되었으면 합니다.

이미지는 Claude AI 로 생성되었습니다.