Mermaid on philipjkim

Marp: Markdown으로 발표 슬라이드를 만들고 Git으로 관리하기

Thu, 23 Jul 2026 13:03:11 +0900

이 글은 Claude Opus 4.8 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

발표 자료를 만들 때마다 PowerPoint나 Keynote를 열면서 “코드는 Git으로 관리하는데 슬라이드는 왜 바이너리 파일로 주고받아야 하지?“라는 생각을 해본 개발자라면, 이 글이 도움이 될 것입니다. 이미 README와 기술 문서를 Markdown으로 쓰고 있다면, 슬라이드도 같은 방식으로 만들 수 있습니다. 이 글에서는 Marp (Markdown Presentation Ecosystem)을 소개합니다.

Marp란 무엇인가

Marp은 Markdown 파일을 발표 슬라이드로 변환해주는 오픈소스 도구 모음입니다. 핵심 아이디어는 단순합니다:

Mermaid 다이어그램 가이드 Part 4: State Diagram

Wed, 28 Jan 2026 10:37:39 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

State Diagram이란?

상태 다이어그램(State Diagram)은 시스템이나 객체가 가질 수 있는 상태(State)와 상태 간의 전이(Transition)를 시각화합니다. 주문 처리, 사용자 인증, TCP 연결 등 유한 상태 기계(Finite State Machine)를 표현할 때 필수적인 도구입니다.

기본 문법

stateDiagram-v2
 [*] --> Idle
 Idle --> Processing
 Processing --> Completed
 Completed --> [*]

stateDiagram-v2
 [*] --> Idle
 Idle --> Processing
 Processing --> Completed
 Completed --> [*]

stateDiagram-v2를 사용하면 최신 렌더러로 그려집니다. 구버전 stateDiagram도 여전히 사용 가능합니다.

Mermaid 다이어그램 가이드 Part 3: Sequence Diagram

Wed, 28 Jan 2026 10:37:36 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Sequence Diagram이란?

시퀀스 다이어그램은 객체들 간의 메시지 교환을 시간 순서에 따라 보여주는 다이어그램입니다. API 호출 흐름, 인증 과정, 트랜잭션 처리 등을 문서화할 때 특히 유용합니다.

기본 문법

sequenceDiagram
 participant A as 클라이언트
 participant B as 서버
 A->>B: 요청
 B-->>A: 응답

sequenceDiagram
 participant A as 클라이언트
 participant B as 서버
 A->>B: 요청
 B-->>A: 응답

Participant 정의

자동 정의

메시지에서 처음 등장하는 이름이 자동으로 participant가 됩니다.

Mermaid 다이어그램 가이드 Part 2: Flowchart 심화 - Subgraph와 레이아웃 제어

Wed, 28 Jan 2026 10:37:33 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Subgraph 기본

Subgraph는 관련된 노드들을 논리적으로 그룹화하는 기능입니다. 시스템의 계층 구조나 도메인 영역을 시각적으로 구분할 때 유용합니다.

기본 문법

flowchart TB
 subgraph 그룹명
 A --> B
 end
 C --> A

flowchart TB
 subgraph 그룹명
 A --> B
 end
 C --> A

ID와 제목 분리

Subgraph에 별도의 ID를 지정하면 참조가 쉬워집니다.

flowchart TB
 subgraph api[API Layer]
 A[Controller]
 B[Service]
 end
 subgraph db[Data Layer]
 C[(MySQL)]
 D[(Redis)]
 end
 A --> B
 B --> C
 B --> D

flowchart TB
 subgraph api[API Layer]
 A[Controller]
 B[Service]
 end
 subgraph db[Data Layer]
 C[(MySQL)]
 D[(Redis)]
 end
 A --> B
 B --> C
 B --> D

Subgraph 방향 제어

이것이 Mermaid 레이아웃의 핵심입니다. direction 키워드로 각 subgraph 내부의 배치 방향을 개별적으로 지정할 수 있습니다.

Mermaid 다이어그램 가이드 Part 1: Flowchart 기본

Wed, 28 Jan 2026 10:37:30 +0900

이 글은 Claude Opus 4.5 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

Mermaid란?

Mermaid는 마크다운 스타일의 텍스트로 다이어그램을 생성하는 JavaScript 기반 도구입니다. 별도의 드로잉 도구 없이도 Git에서 버전 관리가 가능한 다이어그램을 작성할 수 있어, 개발 문서화에 특히 유용합니다.

GitHub, GitLab, Notion, Obsidian 등 다양한 플랫폼에서 기본 지원되며, VS Code 확장 프로그램을 통해 실시간 미리보기도 가능합니다.

Flowchart 기본 문법

Flowchart는 프로세스의 흐름을 시각화하는 가장 기본적인 다이어그램입니다. 노드(Node)와 엣지(Edge)로 구성됩니다.

다이어그램 선언

flowchart TD
 A --> B

flowchart TD
 A --> B

flowchart 키워드로 시작하며, 바로 뒤에 방향을 지정합니다. graph 키워드도 사용 가능하지만 flowchart가 더 많은 기능을 지원합니다.