Jekyll 블로그에 Mermaid 다이어그램 추가하기

Source: Dev.to

Mermaid란?

Mermaid는 텍스트 기반 다이어그램 생성 도구입니다. 마크다운과 유사한 문법으로 다양한 다이어그램을 만들 수 있습니다.

지원하는 다이어그램 종류

• Flowchart (플로우차트)
• Sequence Diagram (시퀀스 다이어그램)
• Class Diagram (클래스 다이어그램)
• State Diagram (상태 다이어그램)
• Entity Relationship Diagram (ERD)
• Gantt Chart (간트 차트)
• Pie Chart (파이 차트)
• 그 외 다수

Jekyll에 Mermaid 설정하기

1. head.html에 스크립트 추가

_includes/head.html 파일에 다음 코드를 삽입합니다.

import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: false });

// Convert Jekyll code blocks to mermaid diagrams
document.addEventListener('DOMContentLoaded', function() {
  document.querySelectorAll('pre code.language-mermaid, div.language-mermaid pre code')
    .forEach(function(codeBlock) {
      const container = codeBlock.closest('div.language-mermaid') || codeBlock.parentElement;
      const pre = document.createElement('pre');
      pre.className = 'mermaid';
      pre.textContent = codeBlock.textContent;
      container.replaceWith(pre);
    });
  mermaid.run();
});

이 스크립트는

• Mermaid 라이브러리를 CDN에서 로드하고,
• Jekyll이 생성한 language‑mermaid 코드 블록을 Mermaid가 인식할 수 있는 형태로 변환하며,
• 페이지 로드가 완료된 뒤 다이어그램을 렌더링합니다.

사용 방법

마크다운 파일에 mermaid 언어를 지정한 코드 블록을 작성하면 됩니다.

graph TD
    A[시작] --> B{조건 확인}
    B -->|Yes| C[처리]
    B -->|No| D[종료]
    C --> D

위 코드는 다음과 같이 렌더링됩니다.

graph TD
    A[시작] --> B{조건 확인}
    B -->|Yes| C[처리]
    B -->|No| D[종료]
    C --> D

다이어그램 예제

Flowchart (플로우차트)

방향 옵션: TB (위→아래), BT (아래→위), LR (왼쪽→오른쪽), RL (오른쪽→왼쪽)

graph LR
    A[사용자 요청] --> B[API Gateway]
    B --> C[인증 서버]
    C --> D{인증 성공?}
    D -->|Yes| E[서비스 처리]
    D -->|No| F[401 에러]
    E --> G[응답 반환]

노드 모양

• [텍스트] – 사각형
• (텍스트) – 둥근 모서리
• {텍스트} – 마름모 (조건)
• ((텍스트)) – 원
• [[텍스트]] – 서브루틴

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

sequenceDiagram
    participant U as User
    participant C as Client
    participant S as Server
    participant DB as Database

    U->>C: 로그인 요청
    C->>S: POST /api/login
    S->>DB: 사용자 조회
    DB-->>S: 사용자 정보
    S-->>C: JWT 토큰
    C-->>U: 로그인 성공

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

classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    class Order {
        +int orderId
        +Date orderDate
        +calculate()
    }
    class Product {
        +String name
        +float price
    }

    User "1" --> "*" Order : places
    Order "*" --> "*" Product : contains

State Diagram (상태 다이어그램)

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : 요청 수신
    Processing --> Success : 처리 완료
    Processing --> Error : 처리 실패
    Success --> [*]
    Error --> Idle : 재시도

ERD (Entity Relationship Diagram)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "ordered in"

    USER {
        int id PK
        string name
        string email
    }
    ORDER {
        int id PK
        int user_id FK
        date created_at
    }
    PRODUCT {
        int id PK
        string name
        decimal price
    }

Gantt Chart (간트 차트)

gantt
    title 프로젝트 일정
    dateFormat  YYYY-MM-DD
    section 기획
    요구사항 분석    :a1, 2026-01-01, 7d
    설계 문서 작성   :a2, after a1, 5d
    section 개발
    백엔드 개발      :b1, after a2, 14d
    프론트엔드 개발  :b2, after a2, 14d
    section 테스트
    통합 테스트      :c1, after b1, 7d

Pie Chart (파이 차트)

pie title 기술 스택 비율
    "JavaScript" : 40
    "Python" : 30
    "Java" : 20
    "기타" : 10

테마 설정

Mermaid는 다양한 테마를 지원합니다. mermaid.initialize() 호출 시 theme 옵션을 지정하면 됩니다.

mermaid.initialize({
  startOnLoad: false,
  theme: 'dark'   // default, dark, forest, neutral
});

마무리

Mermaid를 사용하면 복잡한 다이어그램도 텍스트로 쉽게 작성할 수 있습니다. Git으로 버전 관리가 가능하고, 수정도 간편합니다. 기술 문서나 블로그 포스트에 적극 활용해 보세요.

참고 자료

• Mermaid 공식 문서
• Mermaid Live Editor – 실시간 미리보기