AI/Technical

마크다운에서 머메이드(Mermaid) 사용법 완벽 가이드

Royzero 2025. 12. 16. 15:10
반응형

TL;DR

머메이드(Mermaid)는 마크다운 문법처럼 텍스트로 다이어그램을 정의하는 JavaScript 라이브러리다. 마크다운의 코드 블록에 ```mermaid를 선언하면 브라우저가 자동으로 다이어그램을 렌더링한다. GitHub(2022년 이후), GitLab(13.0+), Notion, Obsidian 등 주요 플랫폼에서 기본 지원한다. 순서도, 시퀀스 다이어그램, 간트 차트, ER 다이어그램, 클래스 다이어그램 등 10가지 이상의 다이어그램 타입을 지원한다.

본문

머메이드란?

머메이드는 마크다운 영감을 받은 텍스트 문법으로 다이어그램과 차트를 동적으로 생성하는 JavaScript 기반 도구다. Knut Sveidqvist가 주도하며 CommonMark 커뮤니티와 함께 표준화 작업을 진행 중이다.

가장 큰 장점은 Visio나 Lucidchart 같은 GUI 도구를 사용하지 않고 순수 텍스트로 다이어그램을 관리할 수 있다는 점이다. 다이어그램 소스 코드를 Git으로 버전 관리하고, 마크다운 파일처럼 협업할 수 있다.

Why it matters: 기술 문서, 아키텍처 설계, 프로젝트 관리 등에서 시각화와 텍스트 관리를 동시에 해결할 수 있어 개발팀의 생산성을 크게 높인다.

마크다운에서 머메이드 사용하는 법

기본 문법

머메이드 다이어그램은 마크다운의 코드 블록에 mermaid 언어 식별자를 지정하여 선언한다:

​```
[다이어그램 코드]
​```

GitHub는 이를 감지하면 HTML 파이프라인과 Viewscreen 렌더링 서비스를 통해 iframe을 생성하고, Mermaid.js 라이브러리가 텍스트를 다이어그램으로 변환한다.

Why it matters: 마크다운 렌더러가 JavaScript를 지원하지 않는 환경에서도 원본 코드가 그대로 표시되므로 호환성이 우수하다.

지원 플랫폼 및 버전

플랫폼 지원 여부 참고 사항
GitHub ✅ 지원 2022년 이후
GitLab ✅ 지원 13.0+, Mermaid 8.4.8 번들
Notion ✅ 지원
Obsidian ✅ 지원
로컬 마크다운 뷰어 ⚠️ 조건부 mermaid.js CDN 스크립트 필요

로컬에서 머메이드를 렌더링하려면 HTML 파일 헤더에 CDN 스크립트를 추가해야 한다:

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

머메이드 다이어그램 타입별 사용법

1. 순서도(Flowchart)

순서도는 프로세스의 단계를 기하학적 도형으로 표현한다. 노드(기하학적 도형)와 엣지(화살표)로 구성된다.

기본 구문:

flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]

주요 요소:

요소 문법 설명
방향 TD, LR, BT, RL Top-Down, Left-Right, Bottom-Top, Right-Left
기본 노드 id[텍스트] 직사각형 박스
둥근 모서리 id(텍스트) 둥근 모서리 박스
마름모(조건) id{텍스트} 의사결정용 마름모
원형 id((텍스트)) 원형 노드
원통 id[(텍스트)] 데이터베이스 표현
화살표 텍스트 `A --> 텍스트| B`

Why it matters: 순서도는 비즈니스 프로세스, 버그 해결 절차, 의사결정 트리 등을 명확히 전달할 수 있어 기술 문서의 필수 요소다.

2. 시퀀스 다이어그램(Sequence Diagram)

시퀀스 다이어그램은 여러 객체 간의 상호작용과 메시지 순서를 시간 흐름에 따라 표현한다.

기본 구문:

sequenceDiagram
    autonumber
    actor C as Client
    participant S as Server
    participant DB as Database

    C->>S: Login (Username, Password)
    S->>DB: Select User Info
    note over DB: Password is not stored
    DB-->>S: Salt & Hash
    S->>S: Check Hash & Generate JWT
    alt Computed Hash Matches
        S-->>C: 200 OK & JWT
    else Wrong Password
        S-->>C: 401 Unauthorized
    end

주요 문법:

요소 문법 의미
참여자 participant Name 시퀀스에 참여하는 객체
동기 메시지 A->>B: message 화살표로 응답 대기
비동기 메시지 A--->B: message 점선 화살표로 응답 미대기
돌려주기 B-->>A: response 점선 화살표로 반환값 표현
활성화 activate B / deactivate B 처리 중 상태 표시
주석 note over A: text 특정 객체 위의 주석
루프 loop Condition ... end 반복 로직 표현
조건 alt Condition ... else ... end 분기 로직 표현
자동 번호 autonumber 메시지에 자동으로 번호 매김

Why it matters: API 호출 흐름, 인증 프로세스, 마이크로서비스 통신 등 시간 순서가 중요한 상호작용을 명확히 문서화할 수 있다.

3. 간트 차트(Gantt Chart)

간트 차트는 프로젝트 일정과 각 작업의 소요 기간을 시각화하는 막대 차트다.

기본 구문:

gantt
    title Simple Project Schedule
    dateFormat YYYY-MM-DD

    section Planning
    Project initiation :a1, 2024-01-01, 1w
    Requirements gathering :a2, after a1, 2w

    section Development
    Implementation :a3, after a2, 4w
    Testing :a4, after a3, 2w

주요 요소:

요소 문법 설명
제목 title Chart Title 차트 제목
날짜 형식 dateFormat YYYY-MM-DD 입력 날짜 형식 지정
섹션 section Section Name 작업 그룹화
작업 Task Name :id, 2024-01-01, 1w 작업 추가(ID, 시작일, 기간)
의존성 Task :after id 다른 작업 완료 후 시작
작업 상태 done, active, crit 완료, 진행 중, 중요도
마일스톤 Milestone :milestone, mid, date, 0d 기간 없는 중요 포인트

Why it matters: 프로젝트 일정, AI 모델 출시 타임라인, 제품 로드맵 등을 팀과 공유할 때 매우 효과적이다.

4. ER 다이어그램(Entity Relationship Diagram)

ER 다이어그램은 데이터베이스 설계에서 엔티티(테이블)와 관계를 표현한다.

기본 구문:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

    CUSTOMER {
        string name
        string custNumber
        string sector
    }

    ORDER {
        int orderNumber
        string deliveryAddress
    }

관계 기호(Crow's Foot Notation):

기호 의미 기호 의미
|o 0 또는 1 o{ 0 이상
|| 정확히 1 |{ 1 이상

Why it matters: 데이터베이스 스키마를 개발자, 기획자와 함께 논의할 때 명확한 시각화가 필수다.

5. 클래스 다이어그램(Class Diagram)

클래스 다이어그램은 객체 지향 설계에서 클래스와 관계를 표현한다.

classDiagram
    Animal <|-- Duck : Inheritance
    class Animal {
        +int age
        +String gender
        +isMammal()
    }

    class Duck {
        +String beakColor
        +swim()
    }

관계 표현:

관계 문법
상속(Inheritance) classA <|-- classB
합성(Composition) classC --* classD
집계(Aggregation) classE --o classF
연관(Association) classG --> classH
의존(Dependency) classK ..> classL

Why it matters: 백엔드 아키텍처, 라이브러리 설계, 디자인 패턴 문서화에 사용된다.

고급 기능 및 커스터마이징

노드 스타일링

클래스 기반 스타일링으로 여러 노드에 일관된 디자인을 적용할 수 있다:

flowchart TD
    A[Node A]
    B[Node B]

    classDef className fill:#f9f,stroke:#333,stroke-width:4px
    class A,B className

스타일 속성:

  • fill: 배경색(HEX)
  • stroke: 테두리색
  • stroke-width: 테두리 두께
  • color: 텍스트색

마크다운 텍스트 포맷

Mermaid 10.0 이상에서는 노드 내 마크다운 포맷을 지원한다:

flowchart TD
    A["**Bold** and *italic*"]
    B["Line 1<br/>Line 2"]

Why it matters: 기술 용어 강조, 복수 라인 텍스트 표현이 가능해져 가독성이 높아진다.

실무 적용 팁

1. Mermaid Live Editor 활용

복잡한 다이어그램은 Mermaid Live에서 작성 및 미리보기 후 코드를 복사하는 것이 효율적이다.

2. 점진적 구축

다이어그램을 작은 단위부터 시작해 하나씩 추가하고 각 단계마다 테스트하는 것이 권장된다. 예를 들어, 간트 차트는 먼저 주요 마일스톤만 표시한 후 세부 작업을 추가하는 방식이다.

3. 버전 관리 활용

다이어그램 코드를 마크다운으로 Git에 커밋하면 변경 이력을 추적할 수 있다. 이는 GUI 도구 스크린샷과 달리 diff 기반 리뷰가 가능하다.

4. 로컬 렌더링(Node.js)

CI/CD 파이프라인에서 SVG/PNG로 변환하려면 Mermaid CLI를 사용한다:

mmdc -i input.mmd -o output.svg

Why it matters: 기술 문서를 PDF로 출판하거나 정적 웹사이트에 임베드할 때 필요하다.

결론

머메이드는 마크다운 문법으로 10여 가지 다이어그램을 정의하고, GitHub·GitLab 등 주요 플랫폼에서 기본 지원하는 강력한 도구다. 순서도, 시퀀스 다이어그램, 간트 차트를 통해 기술 문서의 시각화를 텍스트 기반으로 관리할 수 있으며, 버전 관리와 협업이 용이하다. 복잡한 설계도 Mermaid Live에서 즉시 피드백을 받으며 작성할 수 있으므로, 현대적 기술 문서 작성의 필수 스킬이 되었다.

참고문헌

반응형
저작자표시 비영리 변경금지 (새창열림)

'AI > Technical' 카테고리의 다른 글

구글 FunctionGemma: 스마트폰에서 100% 로컬 실행되는 270M 초경량 에이전트 모델  (1) 2025.12.19
CPU와 GPU, TPU의 차이를 완벽하게 이해하기  (3) 2025.12.17
죽은 프레임워크 이론: React의 플랫폼화와 LLM의 자기 강화 피드백 루프  (4) 2025.12.11
GPU 서버 회사 도입 가이드: 온프레미스 vs 클라우드·호스팅 완전 비교  (7) 2025.12.11
Text2SQL: LLM이 만드는 자연어-SQL 변환의 새로운 경계  (2) 2025.12.09

'AI/Technical'의 다른글

  • 현재글마크다운에서 머메이드(Mermaid) 사용법 완벽 가이드

관련글

티스토리툴바