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

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

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

Marp란 무엇인가#

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

슬라이드 한 장 = Markdown 문서의 한 섹션 (--- 구분자로 분리)
텍스트 파일이므로 Git으로 버전 관리, diff, 코드 리뷰가 그대로 가능
HTML, PDF, PPTX 등 다양한 포맷으로 export

Marp 생태계는 크게 세 가지 구성 요소로 이루어져 있습니다:

구성 요소	역할
Marpit	슬라이드 변환의 핵심 프레임워크. Markdown + CSS 테마를 슬라이드 덱으로 변환
Marp CLI	커맨드라인 변환 도구. HTML/PDF/PPTX/이미지 export, watch 모드, 서버 모드 지원
Marp for VS Code	VS Code 확장. 편집하면서 실시간 프리뷰, export 기능 제공

시작하는 데 필요한 것은 사실상 없습니다. VS Code 사용자라면 확장 하나 설치하면 되고, CLI는 설치 없이 바로 실행할 수 있습니다:

# 실시간 프리뷰 서버
npx @marp-team/marp-cli@latest -s ./slides

# PDF로 변환
npx @marp-team/marp-cli@latest slide.md -o slide.pdf

# PPTX로 변환
npx @marp-team/marp-cli@latest slide.md -o slide.pptx

핵심 문법: Markdown에 directive를 얹은 것#

Marp 문법은 표준 Markdown(CommonMark)에 directive 라는 최소한의 확장을 얹은 형태입니다. 이미 Markdown에 익숙하다면 새로 배울 것은 아래가 거의 전부입니다.

1. 슬라이드 구분 — --- (수평선)이 슬라이드 경계입니다.

2. Global directive — 문서 맨 앞 frontmatter에서 덱 전체 설정을 지정합니다:

---
marp: true          # Marp 활성화 (VS Code 확장에서 필수)
theme: gaia         # 내장 테마: default, gaia, uncover
paginate: true      # 페이지 번호 표시
---

3. Local directive — HTML 주석으로 특정 슬라이드 이후의 설정을 바꿉니다. 언더스코어(_) prefix를 붙이면 해당 슬라이드 한 장에만 적용됩니다(spot directive):

<!-- _class: lead -->        # 이 슬라이드만 lead 레이아웃
<!-- paginate: false -->     # 이 슬라이드부터 페이지 번호 끄기

4. 이미지 문법 확장 — 표준 이미지 문법에 키워드를 추가해 크기 조절과 배경 배치를 제어합니다:

![w:300](image.png)          # 폭 300px로 표시
![bg](background.jpg)        # 슬라이드 배경으로 사용
![bg right:40%](photo.jpg)   # 오른쪽 40% 영역을 이미지로 분할

5. 발표자 노트 — HTML 주석이 presenter view의 노트가 됩니다.

이 외에 코드 블록 문법 하이라이팅, KaTeX/MathJax 수식 렌더링도 기본 지원됩니다.

장점: 슬라이드가 코드처럼 관리된다#

1. Git 친화적#

슬라이드가 plain text이므로 소스 코드와 똑같이 다룰 수 있습니다:

의미 있는 diff: “슬라이드 12의 세 번째 bullet 수정"이 diff 한 줄로 보입니다. PPTX 바이너리에서는 불가능한 일입니다.
코드 리뷰: 발표 자료도 PR로 리뷰받을 수 있습니다. 팀 세미나 자료, 컨퍼런스 발표 준비에 동료 피드백을 리뷰 코멘트로 받는 흐름이 자연스럽습니다.
이력 추적: 지난 분기 발표에서 어떤 수치를 언제 왜 고쳤는지 git log로 추적됩니다.

2. 콘텐츠와 디자인의 분리#

디자인은 CSS 테마가 담당하고, Markdown에는 내용만 남습니다. 팀 공용 테마 CSS를 하나 만들어두면 모든 팀원의 발표 자료가 자동으로 같은 브랜딩을 갖게 됩니다. 발표 직전 “폰트 통일하고 로고 위치 맞추는” 시간이 사라집니다.

3. 작성 속도#

개발자에게 가장 체감되는 부분입니다. 마우스로 텍스트 박스를 옮기는 대신 평소 문서 쓰듯 타이핑만 하면 됩니다. 특히 코드가 많은 기술 발표 에서 차이가 큽니다. PowerPoint에 코드를 붙여넣고 폰트와 하이라이팅을 수동으로 다듬는 대신, 코드 블록에 언어만 지정하면 끝입니다.

4. 재사용성#

기술 문서, 블로그 초안, 슬라이드가 모두 Markdown이므로 콘텐츠 이동이 자유롭습니다. 사내 위키에 쓴 설계 문서의 핵심 섹션을 거의 그대로 발표 자료로 옮길 수 있습니다.

단점: 만능은 아니다#

균형을 위해 한계도 분명히 짚겠습니다.

자유 배치의 부재: 요소를 마우스로 끌어 원하는 위치에 놓는 자유도가 없습니다. 2단 레이아웃 정도는 테마 CSS로 해결되지만, 복잡한 인포그래픽 스타일 슬라이드는 Marp의 영역이 아닙니다.
CSS 지식 요구: 내장 테마를 벗어나 커스텀 디자인을 하려면 결국 CSS를 만져야 합니다. 개발자에게는 장점일 수 있지만 진입 장벽인 것도 사실입니다.
애니메이션/전환 효과 제한: PowerPoint 수준의 개체 애니메이션은 지원되지 않습니다. 화려한 연출이 중요한 발표라면 맞지 않습니다.
비개발자와의 협업: 디자이너나 기획자와 함께 편집해야 하는 자료라면 Markdown + Git 워크플로우 자체가 협업 장벽이 됩니다.
PPTX export의 한계: 기본 PPTX export는 각 슬라이드를 이미지로 넣기 때문에 PowerPoint에서 텍스트 편집이 안 됩니다. (편집 가능한 PPTX를 만드는 실험적 옵션이 있으나 레이아웃 재현이 완벽하지 않습니다.)

정리하면 “내용이 중심인 기술 발표” 에 최적화된 도구이고, “디자인이 중심인 발표” 에는 기존 도구가 낫습니다.

Mermaid 연계: 다이어그램도 텍스트로#

기술 발표에서 아키텍처 다이어그램은 빠지지 않습니다. 보통 draw.io나 Keynote로 그린 다이어그램을 이미지로 export해서 슬라이드에 붙여넣는데, 이 방식은 수정할 때마다 원본 파일을 찾아 열고, 다시 export하고, 다시 붙여넣는 수작업이 반복됩니다. 시간이 지나면 원본 파일이 유실되어 이미지를 처음부터 다시 그리는 일도 흔합니다.

Mermaid를 쓰면 다이어그램도 슬라이드 옆에 텍스트 소스 로 함께 살게 됩니다. 다만 한 가지 알아둘 점이 있습니다. Marp은 Mermaid를 기본 내장하지 않으므로 연계 방법을 선택해야 합니다:

방법 1: 사전 렌더링 (권장) — mermaid-cli로 .mmd 파일을 SVG로 변환한 뒤 이미지로 삽입하는 방식입니다:

# architecture.mmd → architecture.svg
npx -p @mermaid-js/mermaid-cli mmdc -i architecture.mmd -o architecture.svg

![w:800](architecture.svg)

PDF export에서도 안정적으로 동작하고, 빌드 스크립트(Makefile, npm script)에 넣어 자동화하기 좋습니다.

방법 2: HTML 삽입 — --html 옵션을 켜고 슬라이드에 Mermaid 스크립트를 직접 삽입하는 방식도 있지만, PDF export 시 렌더링 타이밍 문제가 생길 수 있어 HTML 출력 전용에 가깝습니다.

핵심은 방법이 아니라 워크플로우의 변화 입니다. 다이어그램 수정이 다음과 같이 바뀝니다:

.mmd 텍스트 파일에서 노드 하나 수정
make slides 실행
끝. diff에는 바뀐 한 줄만 남음

graph LR
    A["slides.md<br/>(Markdown)"] --> C["Marp CLI"]
    B["*.mmd<br/>(Mermaid)"] --> D["mermaid-cli"]
    D --> E["*.svg"]
    E --> C
    C --> F["HTML / PDF / PPTX"]
    style A fill:#90EE90,color:#000000
    style B fill:#90EE90,color:#000000
    style E fill:#FFD700,color:#000000
    style F fill:#87CEEB,color:#000000

슬라이드, 다이어그램, 테마가 전부 텍스트이므로 발표 자료 전체가 하나의 Git 저장소에서 재현 가능한 빌드 산출물 이 됩니다.

CI 자동화까지 얹으면#

Marp CLI는 headless 환경에서 동작하므로 GitHub Actions 같은 CI에 자연스럽게 통합됩니다. 예를 들어:

main 브랜치에 push하면 자동으로 PDF를 빌드해 artifact로 업로드
사내 발표 자료 저장소에서 HTML로 빌드해 GitHub Pages로 배포 (팀원들은 항상 최신 버전을 URL로 열람)
PR마다 프리뷰 빌드를 생성해 리뷰어가 렌더링 결과를 확인

# .github/workflows/slides.yml (발췌)
- name: Build slides
  run: |
    npx -p @mermaid-js/mermaid-cli mmdc -i diagrams/arch.mmd -o assets/arch.svg
    npx @marp-team/marp-cli slides.md -o dist/slides.pdf

“발표 자료 최종본이 어느 메신저 대화방에 있더라?“라는 문제가 구조적으로 사라집니다.

전체 예제#

마지막으로 실제 동작하는 Marp Markdown 예제입니다. 아래 내용을 slides.md로 저장하고 npx @marp-team/marp-cli@latest -s . 을 실행하면 브라우저에서 바로 확인할 수 있습니다.

---
marp: true
theme: gaia
paginate: true
---

<!-- _class: lead -->

# Marp로 만드는 기술 발표

Markdown만 알면 끝

김철수 / 백엔드팀

---

## 오늘 다룰 내용

1. 왜 슬라이드를 코드처럼 관리하는가
2. 아키텍처 개선 제안
3. 마이그레이션 계획

<!-- 발표자 노트: 여기서 청중에게 PPT 스트레스 경험을 물어보기 -->

---

## 현재 아키텍처의 문제

- 단일 DB에 읽기/쓰기 부하 집중
- 캐시 계층 부재로 p99 latency 급증
- **배포 시 전체 서비스 재시작 필요**

![bg right:35%](assets/current-arch.svg)

---

## 개선안: 코드로 보기

```go
func (s *Server) GetUser(ctx context.Context, id string) (*User, error) {
    if u, ok := s.cache.Get(id); ok {
        return u, nil // cache hit
    }
    u, err := s.replica.QueryUser(ctx, id) // read replica
    if err != nil {
        return nil, err
    }
    s.cache.Set(id, u)
    return u, nil
}
```

---

<!-- _class: lead -->

# Q&A

감사합니다
질문은 #backend-arch 채널로도 받습니다

예제에서 확인할 수 있는 요소들:

frontmatter의 global directive (theme, paginate)
 spot directive로 표지/마무리 슬라이드만 중앙 정렬 레이아웃 적용
![bg right:35%] 로 이미지 분할 배치 (사전 렌더링한 Mermaid SVG를 여기에 넣습니다)
코드 블록은 언어 지정만으로 문법 하이라이팅
HTML 주석으로 발표자 노트 작성

마치며#

Marp은 “슬라이드 제작 도구"라기보다 “발표 자료를 소프트웨어 산출물처럼 다루게 해주는 도구"에 가깝습니다. diff, 리뷰, 빌드, 배포라는 개발자의 익숙한 워크플로우에 발표 자료가 편입되는 순간, 자료의 유지보수 비용이 눈에 띄게 줄어듭니다. 다음 팀 세미나 자료부터 slides.md 로 시작해보시기 바랍니다.