Mermaid 다이어그램 문법: Markdown 및 Obsidian 예제 가이드

Mermaid 다이어그램은 Mermaid JS 라이브러리를 사용하여 텍스트 코드로부터 생성되는 시각적 표현 방식입니다. Knut Sveidqvist가 2014년경 시작한 이 오픈 소스 프로젝트는 소프트웨어 문서화에서 텍스트 기반 다이어그램의 표준으로 자리 잡았습니다. 2026년 현재, GitHub, GitLab 및 주요 문서화 툴을 포함한 대부분의 플랫폼에서 Mermaid 문법을 기본적으로 렌더링합니다.

이 가이드에서는 Mermaid 문법, 핵심 다이어그램 유형, Markdown 및 Obsidian 렌더링 방식, 내보내기 옵션, 그리고 자주 발생하는 오류 해결 방법을 설명합니다.

기본 문법의 예시는 다음과 같습니다:

graph TD
    A[Start] --> B[Process]
    B --> C[Complete]

“코드형 다이어그램(Diagrams as Code)” 접근 방식은 버전 관리를 통해 유지보수성을 향상시키고 엔지니어링 팀 간의 협업을 단순화합니다. 이어지는 섹션에서는 주요 다이어그램 유형, 단계별 작성법, 정적 이미지를 선호하는 이해관계자를 위한 다이어그램 내보내기 방법을 다룹니다.

Mermaid 문법 요약표 (Cheat Sheet)

다이어그램 유형	시작 키워드	주요 사용 목적
순서도 (Flowchart)	flowchart TD 또는 flowchart LR	프로세스 및 의사결정 흐름
시퀀스 (Sequence)	sequenceDiagram	요청, 응답 및 서비스 간 상호작용
개체 관계도 (ERD)	erDiagram	데이터베이스 엔티티 및 관계
상태 (State)	stateDiagram-v2	상태 및 생명주기(Lifecycle) 변경
간트 차트 (Gantt)	gantt	마일스톤 및 일정 관리
클래스 (Class)	classDiagram	도메인 및 객체 모델링

모든 Mermaid 블록에는 하나의 시작 키워드가 필요합니다. 노드 ID는 짧고 안정되게 유지하는 것이 좋으며, 화면에 표시되는 라벨에는 더 길고 읽기 쉬운 텍스트를 포함할 수 있습니다.

Mermaid 다이어그램이란 무엇이며 왜 사용해야 할까요?

Mermaid 다이어그램은 Mermaid JavaScript 라이브러리가 해석하는 가벼운 텍스트 문법을 통해 생성됩니다. 드래그 앤 드롭 방식의 UI 대신 Mermaid 다이어그램 코드를 작성하면 라이브러리가 이를 SVG 그래픽으로 변환합니다.

Mermaid 코드가 시각 자료로 변환되는 방식:

• graph TD; A –> B; 는 위에서 아래로 향하는 순서도로 렌더링됩니다.

• sequenceDiagram 블록은 메시지 흐름을 보여주는 시퀀스 다이어그램이 됩니다.

• erDiagram 정의는 개체 관계도(ERD)를 생성합니다.

텍스트 기반 다이어그램의 주요 장점:

• 누구나 쉽게 수정할 수 있는 사람이 읽기 쉬운 평문 텍스트

• 정확히 변경된 내용을 보여주는 Git 친화적인 diff

• 풀 리퀘스트(PR) 시 더욱 쉬워지는 코드 리뷰

• 관리할 독자적인 다이어그램 파일 포맷이 없음

2026년 기준 실무 활용 사례:

• 시퀀스 다이어그램으로 마이크로서비스 인증 흐름 문서화

• 커밋부터 운영 배포까지의 CI/CD 파이프라인 매핑

• 간트 차트를 활용한 2026년 2분기 제품 출시 마일스톤 계획

Mermaid 다이어그램은 Markdown 기반 문서, 내부 위키, 개발자 포털과 자연스럽게 통합되어 조직 전체의 문서화 프로세스를 단순화합니다.

핵심 Mermaid 다이어그램 유형

Mermaid는 다양한 차트 유형을 지원합니다. 이 섹션에서는 방대한 레퍼런스 대신 가장 유용한 핵심 유형을 소개합니다.

주요 다이어그램 유형:

유형	키워드	추천 활용 분야
순서도 (Flowcharts)	graph TD / flowchart LR	프로세스 흐름, 의사결정 나무
시퀀스 다이어그램	sequenceDiagram	API 호출, 서비스 간 상호작용
클래스 다이어그램	classDiagram	객체 모델, 도메인 설계
상태 다이어그램	stateDiagram-v2	생명주기 상태, 워크플로우
개체 관계도 (ERD)	erDiagram	데이터베이스 스키마 설계
사용자 여정 (User Journey)	journey	고객 경험 매핑
간트 차트	gantt	프로젝트 일정, 로드맵
파이 차트	pie	비율 데이터 시각화
Git 그래프	gitGraph	브랜치 전략 시각화

실제 활용 예시:

• 프론트엔드 → API 게이트웨이 → 결제 서비스 API 흐름을 위한 시퀀스 다이어그램

• 의존성이 포함된 2026년 2분기 기능 로드맵 간트 차트

• 주문 생명주기 상태 다이어그램: 대기 중 → 결제 완료 → 배송 중 → 배송 완료

순서도, 시퀀스 다이어그램, ERD, 상태 다이어그램은 소프트웨어 팀에서 가장 흔히 사용됩니다. 제품 및 운영 팀은 주로 사용자 여정, 간트 차트, 파이 차트를 활용합니다.

sequenceDiagram
    participant User
    participant API
    User->>API: POST /login
    API-->>User: 200 OK + Token

Mermaid 다이어그램 작성 방법

순서도를 빠르게 작성하려면 먼저 기본 구조를 이해해야 합니다. 텍스트 에디터와 Mermaid 문법만 있으면 다이어그램을 쉽게 만들 수 있습니다.

단계별 작성 프로세스:

1. 다이어그램 키워드(graph TD, sequenceDiagram, gantt)로 시작합니다.

2. ID와 라벨을 사용하여 노드나 참여자를 정의합니다.

3. 화살표나 관계선으로 요소를 연결합니다.

4. 필요한 경우 라벨과 그룹화(subgraph)를 추가합니다.

다음은 작동 가능한 로그인 프로세스 순서도 예시입니다:

graph TD
    U[User] --> LP[Login Page]
    LP --> AS[Auth Service]
    AS --> DB[(User Database)]
    AS -->|Success| DASH[Dashboard]
    AS -->|Failure| ERR[Error Page]

화살표 유형 및 라벨:

• –> 기본 단방향 화살표를 생성합니다.

• –>|label| 연결선에 조건부 텍스트를 추가합니다.

• — 화살표가 없는 일반 선을 그립니다.

• -.-> 간접적인 관계를 나타내는 점선 화살표를 생성합니다.

Mermaid는 ELK 레이아웃 알고리즘을 사용하여 노드를 자동으로 정렬합니다. 수동 위치 조정 대신 논리적 구조와 이름 지정에 집중하세요. 배치를 위해 별도의 코드를 작성할 필요가 없습니다.

2026년 Mermaid 다이어그램을 사용할 수 있는 플랫폼

현재 많은 주요 플랫폼에서 Mermaid를 기본적으로 지원하거나 확장 프로그램을 통해 지원하므로 즉시 작성에 착수할 수 있습니다.

주요 활용 환경:

• GitHub 및 GitLab: README.md, 문서, 이슈, 위키에서 기본 렌더링 지원

• 정적 사이트 생성기: 확장 프로그램을 통한 Docusaurus, MkDocs, Sphinx 지원

• 내부 개발자 포털: Backstage 및 사용자 지정 React 앱

• 노트 앱: Mermaid 차트를 내장 지원하는 Notion 및 Obsidian

Visual Studio Code와 JetBrains IDE는 확장 프로그램을 통해 실시간 라이브 프리뷰를 지원하므로 입력과 동시에 시각화할 수 있습니다. 이는 커밋 전에 문법 오류를 잡는 데 도움이 됩니다.

Confluence Cloud와 같은 일부 플랫폼은 마켓플레이스 부가 기능이 필요합니다. 팀에서는 다이어그램 소스를 Git 리포지토리에 저장하고, 가시성을 위해 내보낸 이미지를 함께 보관하는 방식을 자주 사용합니다.

다양한 플랫폼에서의 Mermaid 다이어그램 렌더링

렌더링 과정은 Mermaid 텍스트를 시각적인 SVG/HTML 그래픽으로 변환합니다. 방식은 사용하는 호스트 플랫폼에 따라 다릅니다.

일반적인 패턴: mermaid 언어 식별자가 지정된 코드 블록 내에 Mermaid 코드를 작성합니다. GitHub, GitLab, 문서 생성기는 브라우저에서 볼 때 이 블록을 자동으로 그래픽으로 렌더링합니다.

로컬 개발 환경에서는 확장 프로그램이나 플러그인이 라이브 프리뷰를 제공합니다. Sphinx 기반 문서에서는 빌드 중 다이어그램을 생성하는 sphinxcontrib-mermaid 같은 확장 프로그램을 활성화하여 렌더링합니다.

Markdown 파일에서 Mermaid 렌더링하기

Markdown 내에서 Mermaid를 렌더링하려면:

1. 백틱 3개로 코드 블록을 엽니다.

2. 언어 식별자로 mermaid를 지정합니다.

3. 내부에 다이어그램 정의를 작성합니다.

4. 백틱 3개로 코드 블록을 닫습니다.

```mermaid
flowchart LR
    A[Step 1] -->|Process| B[Step 2]
    B -->|Complete| C[Step 3]
```

• GitHub, GitLab 및 현대적인 문서 사이트에서는 이 방식을 직접 지원합니다.

• 프로덕션에 병합하기 전에 미리보기 환경에서 렌더링 상태를 테스트하세요.

• Mermaid 차트의 기본 테마는 대부분의 기술 문서에 잘 어울립니다.

Obsidian에서 Mermaid 렌더링하기

Obsidian은 읽기 보기(Reading View)와 라이브 프리뷰(Live Preview) 모두에서 mermaid 코드 블록을 내장 렌더링합니다. Mermaid 지원이 기본 포함되어 있어 기초적인 다이어그램에는 커뮤니티 플러그인이 필요하지 않습니다.

다이어그램이 렌더링되지 않을 경우:

1. 코드 블록 시작 부분이 정확히 ```mermaid 인지 확인합니다.
2. 첫 번째 줄에 flowchart LR과 같은 유효한 다이어그램 키워드가 있는지 확인합니다.
3. 구두점이 많은 라벨은 큰따옴표로 감쌉니다. 예: A["Review: blocked?"].
4. 예제를 두 개의 노드로 줄인 다음, 문제가 발생하는 구문이 나올 때까지 줄을 다시 추가해 봅니다.
5. 설치된 Obsidian 버전이 복사해 온 최신 Mermaid 문법을 지원하는지 확인합니다.

Obsidian 전용 Markdown 서식 문법은 Obsidian 서식 체계 요약표를 참조하세요.

IDE 및 로컬 툴에서 Mermaid 렌더링하기

Visual Studio Code의 Mermaid 플러그인을 사용하면 편집과 동시에 분할 화면으로 라이브 프리뷰를 볼 수 있습니다. 여러 확장 프로그램이 구문 강조 및 오류 수정 제안 기능을 제공합니다.

JetBrains IDE도 플러그인을 통해 유사한 기능을 제공하며, 오류 힌트 및 내보내기 옵션을 포함합니다. 일부 툴의 다이어그램 수정 버튼은 흔한 문법 오류를 자동으로 해결해 줍니다.

로컬 미리보기는 Git 리포지토리에 푸시하기 전 오류를 잡는 데 유용합니다. 개발 환경 설정 문서에 추천 확장 프로그램 세트를 표준화해 두세요.

Mermaid 다이어그램 내보내기 및 공유하기

코드 기반 편집은 개발자에게 유용하지만, 이해관계자들은 Microsoft PowerPoint 발표나 보고서용 정적 이미지를 선호하는 경우가 많습니다.

주요 내보내기 포맷:

• PNG: 메신저 툴을 통한 빠른 공유

• SVG: 슬라이드용 고품질 벡터 그래픽

• PDF: 인쇄용 문서 패키지

내보내기 워크플로우는 툴에 따라 다릅니다. 자체 내보내기 버튼을 지원하는 툴도 있고, Mermaid Chart 에디터나 Mermaid Live Editor 같은 온라인 툴을 활용해야 하는 경우도 있습니다. CLI 툴을 사용하면 CI/CD 파이프라인에서 여러 파일의 이미지를 일괄 생성할 수도 있습니다.

다이어그램을 언제든 수정할 수 있도록 내보낸 이미지와 함께 원본 Mermaid 소스를 항상 유지 관리하세요.

Mermaid 다이어그램을 이미지 포맷으로 변환하기

온라인 에디터 활용 워크플로우:

1. 브라우저에서 Mermaid Live Editor를 엽니다.

2. Mermaid 코드를 붙여넣거나 샘플 다이어그램을 템플릿으로 사용합니다.

3. 스타일 설정을 조정합니다.

4. 필요한 경우 테마를 설정합니다(다크 모드/라이트 모드 옵션 사용 가능).

5. “Download SVG” 또는 “Download PNG”를 클릭합니다.

내보낸 다이어그램의 폰트와 색상이 브랜드 가이드라인과 일치하는지 확인하세요. GitHub 캡처 이미지는 래스터화되어 확대 시 깨질 수 있으므로 발표 자료에는 가능한 한 SVG 내보내기를 사용하세요.

Mermaid 다이어그램의 권장 사항 및 한계

Mermaid는 강력하지만, 명확한 목적과 구조를 가지고 작성할 때 가장 효과적입니다.

권장 사항:

• 각 다이어그램은 하나의 집중된 개념만 담도록 제한하세요.

• 직관적인 노드 라벨과 일관된 명명 규칙을 사용하세요.

• 관련 단계는 서브그래프(subgraph) 블록으로 그룹화하세요.

• 복잡한 다이어그램은 하나의 거대한 그래픽 대신 별도의 파일로 나누어 관리하세요.

고려해야 할 한계:

• 크고 복잡한 시스템은 코드로 관리하기가 어려워집니다.

• 레이아웃 제어가 대략적이며 픽셀 단위의 정밀한 배치는 불가능합니다.

• 기존 전용 드로잉 툴이나 화이트보드 소프트웨어에 비해 스타일링 자유도가 낮습니다.

• 시각적 디자인 중심의 아이디어 구상이나 UI 목업(Mockup)에는 적합하지 않습니다.

아키텍처 개요나 워크플로우 작성에는 Mermaid를 활용하세요. 픽셀 단위의 정밀한 레이아웃이나 복잡한 네트워크 토폴로지가 필요한 경우에는 전용 툴을 사용하는 것이 좋습니다.

Mermaid 다이어그램 빠르게 시작하기

신규 사용자를 위한 체크리스트:

1. 하나의 다이어그램 유형을 선택합니다(보통 순서도로 시작하는 것을 추천).

2. 비주얼 에디터나 AI 기능이 포함된 확장 프로그램을 설치하거나 Mermaid Live Editor를 엽니다.

3. 현재 프로젝트의 실제 프로세스(예: 2026년 배포 파이프라인)를 시각화해 봅니다.

4. 문법 패턴을 익혀가며 점진적으로 다이어그램을 확장합니다.

주요 참고 자료:

• 전체 문법이 안내된 Mermaid 공식 문서

• AI 내장 기능을 테스트해 볼 수 있는 Mermaid Live Editor

• 코드 스니펫과 템플릿을 제공하는 VS Code 확장 프로그램

• 팀 협업을 위한 플랫폼 계정 검토

엔지니어링 핸드북에 명명 규칙, 선호하는 다이어그램 유형, 권한 관리를 담은 “다이어그램 지침” 섹션을 추가하세요. 자연어 설명과 AI 챗봇 툴을 조합하면 기술적 배경에 상관없이 팀원 누구나 빠르게 다이어그램을 작성할 수 있습니다.

Mermaid 다이어그램을 도입하면 일반 소스 코드와 동일한 리뷰 및 자동화 프로세스를 문서화에 적용할 수 있습니다. 머신러닝 파이프라인을 정리하는 엔지니어든 워크플로우를 매핑하는 프로젝트 관리자든, Mermaid는 팀에 버전 관리되는 시각 자료를 제공합니다. 오늘 첫 번째 다이어그램을 작성해 보세요.