Mermaid.js 가이드: 텍스트로 다이어그램 만들기 (플로우차트, 시퀀스 및 간트 차트)

1 1. Mermaid란 무엇인가?
- 1.1 Mermaid의 개요 및 주요 기능
- 1.2 Mermaid의 주요 사용 사례 및 이점
  - 1.2.1 사용 사례
  - 1.2.2 이점
2 2. Mermaid의 기본 사용법
3 3. Mermaid.js를 사용한 다이어그램 생성
4 4. WordPress에서 Mermaid 사용 방법
5 6. 요약

1. Mermaid란 무엇인가?

Mermaid의 개요 및 주요 기능

Mermaid는 텍스트 기반 정의를 사용하여 다이어그램과 차트를 생성할 수 있게 해주는 JavaScript 라이브러리입니다. 이 도구를 사용하면 코드를 작성하는 것만으로도 시각적 다이어그램을 쉽게 생성할 수 있습니다. 플로우차트, 시퀀스 다이어그램, 간트 차트 등을 빠르게 생성할 수 있기 때문에 소프트웨어 개발자, 프로젝트 매니저 등 많은 사람들이 널리 사용합니다.

Mermaid의 가장 큰 강점 중 하나는 코드만으로 다이어그램을 정의할 수 있다는 점입니다. 이는 GUI에 의존하지 않고 다이어그램을 쉽게 편집하고 관리할 수 있게 합니다. Mermaid는 GitHub와 Notion 같은 플랫폼에 통합되어 있어 다양한 상황에서 유연하게 사용할 수 있습니다.

Mermaid의 주요 사용 사례 및 이점

사용 사례

소프트웨어 개발을 위한 플로우차트와 시퀀스 다이어그램 생성.
프로젝트 계획을 위한 간트 차트 생성.
Markdown 파일과 Wiki 문서에 시각적 표현 추가.

이점

간단한 구문: 프로그래밍 코드처럼 작성할 수 있어 초보자도 쉽게 사용할 수 있습니다.
코드 기반 관리: 소스 제어 도구(예: Git)를 사용하여 버전을 관리할 수 있습니다.
빠른 생성 및 업데이트: 코드를 편집하는 것만으로 다이어그램 변경이 즉시 반영됩니다.
확장성과 맞춤화: CSS로 디자인을 맞춤화하고 JavaScript로 기능을 확장할 수 있습니다.

2. Mermaid의 기본 사용법

설치 방법

Mermaid.js는 CDN 링크를 사용하거나 npm을 사용하여 두 가지 방법으로 설치할 수 있습니다.

1. CDN 링크 사용

HTML 파일에 다음 스크립트 태그를 추가하세요.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
  </div>
</body>
</html>

2. npm 사용

Node.js 환경이 준비되어 있다면 다음 명령어로 설치할 수 있습니다.

npm install mermaid

이 방법으로 JavaScript 프로젝트의 일부로 Mermaid를 통합할 수 있습니다.

기본 구문 및 문법

Mermaid.js를 사용하면 직관적인 텍스트 기반 구문을 사용하여 다이어그램을 생성할 수 있습니다. 다음은 몇 가지 일반적인 예입니다.

1. 플로우차트

아래는 플로우차트 정의의 예입니다.

graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]

2. 시퀀스 다이어그램

시스템 워크플로를 보여주는 시퀀스 다이어그램은 다음과 같이 작성할 수 있습니다.

sequenceDiagram
  participant A as User
  participant B as Server
  A->>B: Send request
  B-->>A: Return response

3. 간트 차트

프로젝트 관리에 유용한 간트 차트는 다음과 같이 작성할 수 있습니다.

gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Planning
  Task A :a1, 2024-01-01, 10d
  Task B :a2, after a1, 7d
  Task C :a3, after a2, 5d

지원되는 다이어그램 유형

Mermaid.js는 다음 유형의 다이어그램과 차트를 지원합니다.

플로우차트 : 프로세스의 흐름을 보여줍니다.
시퀀스 다이어그램 : 통신 프로토콜과 절차를 시각화합니다.
간트 차트 : 프로젝트 관리 및 스케줄링에 사용됩니다.
클래스 다이어그램 : 객체 지향 설계에 사용됩니다.
상태 다이어그램 : 상태 전환을 나타냅니다.
파이 차트 : 데이터 비율을 시각화합니다.

3. Mermaid.js를 사용한 다이어그램 생성

HTML에 Mermaid 임베드하는 방법

Mermaid.js는 HTML에 쉽게 임베드할 수 있습니다. 아래 단계를 따라 다이어그램을 생성하세요.

1. 기본 HTML 구조

다음 코드는 HTML 파일에서 Mermaid.js를 사용하는 최소 예를 보여줍니다.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Mermaid Diagram</title>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <h1>Flowchart Example</h1>
  <div class="mermaid">
    graph TD;
      A[Start] --> B[Process 1]
      B --> C[Process 2]
      C --> D[End]
  </div>
</body>
</html>

2. 여러 다이어그램 표시하기

여러 개의 다이어그램을 표시하려면 HTML에 다음과 같이 div 태그를 여러 개 추가하세요.

<div class="mermaid">
  graph TD;
    A --> B;
    B --> C;
</div>
<div class="mermaid">
  sequenceDiagram
    participant A as User
    participant B as Server
    A->>B: Send request
    B-->>A: Return response
</div>

JavaScript를 사용한 초기화 및 설정

1. 초기화 설정

다음 코드는 Mermaid.js를 프로그래밍 방식으로 초기화합니다.

mermaid.initialize({
  startOnLoad: true,
  theme: 'forest',
  flowchart: { curve: 'basis' },
});

이 설정을 사용하면 테마가 forest로 변경되고, 플로우차트 선이 곡선 모양으로 맞춤 설정됩니다.

2. 다이어그램을 동적으로 추가하기

다음 예시는 JavaScript를 사용해 다이어그램을 동적으로 생성하는 방법을 보여줍니다.

const code = `
graph LR;
  X[Start] --> Y[Next step];
  Y --> Z[End];
`;
const element = document.querySelector('#dynamicChart');
element.innerHTML = code;
mermaid.init(undefined, element);

실용적인 코드 예시와 설명

예시 1: 시퀀스 다이어그램 만들기

<div class="mermaid">
  sequenceDiagram
    participant User as User
    participant Server as Server
    User->>Server: Data request
    Server-->>User: Data response
</div>

예시 2: 간트 차트 만들기

<div class="mermaid">
  gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Development Phase
      Design :done, 2024-01-01, 2024-01-07
      Implementation :active, 2024-01-08, 2024-01-20
      Testing :2024-01-21, 2024-01-30
</div>

4. WordPress에서 Mermaid 사용 방법

플러그인 소개 및 설정

WordPress에서 Mermaid.js를 사용하려면 전용 플러그인을 설치하는 것이 가장 쉽습니다. 다음은 인기 있는 옵션들입니다.

1. Mermaid 플러그인 – “Mermaid Markdown Syntax Highlighting”

이 플러그인을 사용하면 포스트 안에서 바로 Mermaid 구문을 사용할 수 있습니다.

설치 단계

WordPress 관리자 대시보드에 로그인합니다.
메뉴에서 플러그인 → 새로 추가 를 클릭합니다.
검색창에 Mermaid Markdown Syntax Highlighting 을 입력합니다.
플러그인을 설치하고 활성화합니다.

설정 단계

활성화 후 설정 화면에서 기본 옵션을 조정할 수 있습니다.
테마 및 시작 시 자동 로드 와 같은 설정을 맞춤화합니다.

포스트에 다이어그램 표시하기

플러그인을 설치한 후, 다음과 같은 숏코드를 사용해 포스트 안에 다이어그램을 표시할 수 있습니다.

예시: 플로우차트 삽입

[mermaid]
graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]
[/mermaid]

예시: 시퀀스 다이어그램 삽입

[mermaid]
sequenceDiagram
  participant User
  participant Server
  User->>Server: Send request
  Server-->>User: Return response
[/mermaid]

예시: 간트 차트 삽입

[mermaid]
gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Development
    Design :done, 2024-01-01, 2024-01-07
    Implementation :active, 2024-01-08, 2024-01-20
    Testing :2024-01-21, 2024-01-30
[/mermaid]

참고 사항 및 문제 해결

1. 다이어그램이 렌더링되지 않을 때 대처 방법

원인 1: 플러그인이 올바르게 활성화되지 않았습니다. → 플러그인 설정을 다시 확인하고 활성화되어 있는지 확인하세요.
원인 2: Mermaid.js 스크립트가 로드되지 않았습니다. → 테마나 다른 플러그인과 충돌할 수 있으니, 플러그인을 하나씩 비활성화해 충돌 원인을 찾으세요.

2. 플러그인 없이 수동 설정

플러그인을 사용하고 싶지 않다면, 테마의 functions.php에 다음 코드를 추가하여 Mermaid.js를 수동으로 삽입할 수 있습니다.

.“` function add_mermaid_script() { echo ‘‘; } add_action(‘wp_footer’, ‘add_mermaid_script’);






## 5. Mermaid 사용을 위한 모범 사례



### 복잡한 다이어그램 관리 방법



#### 1. 코드를 분할하고 정리하기



복잡한 다이어그램을 만들 때는 다음 팁을 따라 코드를 정리하세요.



* **각 섹션에 주석 추가**

%% Start of the flowchart graph TD; A[Start] –> B[Process 1] %% Branching logic B –> C[Process 2] B –> D[Process 3]

* **템플릿을 만들고 재사용하기** 대규모 프로젝트에서는 템플릿을 준비하고 여러 다이어그램 간 일관성을 유지하는 것이 중요합니다.



#### 2. 외부 파일에서 다이어그램 관리하기



Mermaid 코드를 HTML이나 Markdown 파일에 직접 삽입하는 대신 외부 파일에 저장할 수 있습니다. 이렇게 하면 유지 관리가 용이해집니다.



예시: Mermaid 코드를 **diagram.mmd**라는 파일에 저장하고 HTML에서 로드합니다.

### 사용자 정의 및 테마 설정



#### 1. 테마 적용



Mermaid.js는 여러 내장 테마를 제공하므로 시각적으로 매력적인 스타일로 쉽게 전환할 수 있습니다.



**테마 목록**



* 기본
* 다크
* 포레스트
* 네온



**구성 예시**

mermaid.initialize({ theme: ‘dark’, });

#### 2. 사용자 정의 CSS 적용



보다 세부적인 디자인 조정이 필요하면 CSS로 스타일을 정의할 수 있습니다.

.mermaid text { font-family: Arial, sans-serif; fill: #333; }

### 성능 고려 사항



#### 1. 초기화 시점 조정



페이지 로드 시 다이어그램을 초기화하는 대신 사용자가 필요할 때만 Mermaid를 초기화할 수 있습니다. 이렇게 하면 처리 부하가 감소합니다.

const config = { startOnLoad: false, };

mermaid.initialize(config);

// Render only when needed document.getElementById(‘render-btn’).addEventListener(‘click’, () => { mermaid.init(); }); “`

2. 정적 이미지로 변환

성능이 특히 중요한 경우 Mermaid로 생성된 다이어그램을 이미지 파일로 내보내 정적 이미지로 사용할 수 있습니다. 이렇게 하면 브라우저의 부하를 최소화합니다.

6. 요약

Mermaid.js의 가치와 편리함

Mermaid.js는 코드 기반 정의를 사용해 다이어그램을 만들 수 있는 강력한 JavaScript 라이브러리입니다. 흐름도, 시퀀스 다이어그램, 간트 차트 등 다양한 유형의 다이어그램을 손쉽게 렌더링할 수 있어 개발자와 프로젝트 관리자에게 매우 유용한 도구입니다.

이 라이브러리의 가장 큰 장점 중 하나는 간단한 문법으로 복잡한 다이어그램을 효율적으로 만들 수 있다는 점입니다. 또한 WordPress와 같은 CMS 플랫폼과 통합할 수 있어 블로그 포스트와 기술 문서에서 시각 정보를 효과적으로 제공할 수 있습니다.

각 섹션 요약

Mermaid란? Mermaid.js의 기본 개요, 사용 사례 및 도입 장점을 설명했습니다.
Mermaid 기본 사용법 설치 방법부터 기본 문법까지 실용적인 사용을 위한 기본을 소개했습니다.
Mermaid.js로 다이어그램 만들기 HTML과 JavaScript를 사용해 다이어그램을 만드는 자세한 방법을 제공했습니다.
WordPress에서 Mermaid 사용하기 플러그인 사용법 및 포스트 내 실제 예시를 포함해 WordPress와 Mermaid를 통합하는 방법을 다루었습니다.
Mermaid 사용 모범 사례 코드 관리, 성능 최적화, 디자인 커스터마이징에 대한 실용적인 조언을 제공했습니다.

Mermaid.js의 향후 가능성

answer.Mermaid.js는 오픈 소스 프로젝트이며, 앞으로도 새로운 기능과 지원 포맷을 계속 추가할 수 있습니다. 또한 GitHub, Notion, WordPress와 같은 다양한 플랫폼에서 점점 더 많이 지원되고 있어, 그 잠재적 사용 사례가 더욱 확대될 것으로 기대됩니다.

비즈니스 문서, 프레젠테이션, 프로젝트 관리 도구 향상 등 다양한 목적에 적용할 수 있기 때문에, Mermaid.js를 지속적으로 학습하고 연습하면 더욱 효과적으로 활용할 수 있습니다.

최종 메모

이 기사에서는 Mermaid.js의 기본부터 실용적인 사용법까지 다루었습니다. 초보자에게 친숙하고 전문 문서에도 유용하므로 꼭 사용해 보세요.

필요할 때마다 이 가이드를 다시 참고하고 Mermaid.js를 실제 프로젝트와 기술 문서에 통합해 보세요.

Prev

2026-01-19
JavaScript 배열 splice() 설명: 삭제, 삽입, 교체 (실용 예제 포함)
Next
記事がありません