Imported from joonlab/joonlab-claudecode-setting-for-share (claude/skills/slidev-master/SKILL.md). Install upstream with npx skills add joonlab/joonlab-claudecode-setting-for-share --skill slidev-master. Copyright stays with the author.

Slidev Master Skill

개발자를 위한 마크다운 기반 프레젠테이션 프레임워크 Slidev의 완벽 가이드.

활성화 조건

다음 요청 시 이 스킬 사용:

• Slidev 프레젠테이션 생성/수정
• 기술 발표자료, 컨퍼런스 슬라이드
• 코드 데모가 포함된 워크샵 자료
• 마크다운 기반 슬라이드 제작

핵심 원칙 (Critical Rules)

1. 마크다운린트 설정 (필수)

슬라이드 작성 전 반드시 .markdownlint.json 생성:

{
  "MD003": false,
  "MD024": false,
  "MD025": false,
  "MD026": false,
  "MD033": false,
  "MD041": false
}

2. 접근성 기반 디자인 (Critical)

폰트 크기 (연구 기반):

• 본문: 최소 18pt, 권장 18-24pt
• 제목: 최소 24pt 이상
• Sans-serif 글꼴 사용 (Arial, Helvetica, Inter)
• 이탤릭, 밑줄, ALL CAPS 본문 사용 금지

색상 대비:

• 일반 텍스트: 최소 4.5:1 대비율
• 큰 텍스트 (>24pt): 최소 3:1 대비율
• 색맹 친화적 팔레트 사용 (ColorBrewer 검증)
• 색상만으로 정보 전달 금지 (패턴/라벨 병행)

기본 스타일 설정:

---
theme: default
---

<style>
h1 { font-size: 3rem; }      /* ~48pt */
h2 { font-size: 2rem; }      /* ~32pt */
h3 { font-size: 1.5rem; }    /* ~24pt */
p, li { font-size: 1.25rem; } /* ~20pt */

body {
  font-family: 'Inter', 'Helvetica Neue', Arial, sans-serif;
}
</style>

3. 콘텐츠 원칙

슬라이드당 하나의 아이디어:

• 설명에 2분 이상 필요하면 분할
• 제목은 명확한 주장 형태 ("성능" X → "API가 10K req/sec 처리" O)
• 제목만 읽어도 스토리가 전달되어야 함

최소 텍스트:

• 슬라이드당 50단어 미만
• 완전한 문장 대신 키워드/구문
• 상세 설명은 발표자 노트에

인지 부하 관리:

• 슬라이드당 최대 6개 요소 (제목 + 다이어그램 + 불릿 등)
• 6개 초과 시 v-click으로 점진적 공개

프로젝트 구조

기본 구조

project/
├── slides.md              # 메인 프레젠테이션
├── .markdownlint.json     # 린트 설정 (필수!)
├── package.json
├── components/            # 커스텀 Vue 컴포넌트
├── layouts/               # 커스텀 레이아웃
├── pages/                 # 외부 슬라이드 파일
├── public/                # 정적 에셋 (이미지 등)
│   └── images/
└── styles/                # 커스텀 CSS

모듈화된 구조 (30+ 슬라이드)

presentation/
├── slides.md                      # 마스터 파일
├── .markdownlint.json
├── slides/
│   ├── 01-title.md
│   ├── 02-hook.md
│   ├── 03-problem-statement.md
│   ├── 04-architecture-overview.md
│   └── ...
└── public/images/

마스터 파일 예시:

---
theme: default
title: My Presentation
---

---
src: ./slides/01-title.md
---
<!-- Slide 1: Title -->

---
src: ./slides/02-hook.md
---
<!-- Slide 2: Opening Hook -->

주의: 주석은 닫는 --- 뒤에 (frontmatter 블록 내부 아님)

Frontmatter 설정

전역 설정 (Headmatter)

---
# 테마
theme: default  # seriph, apple-basic, shibainu, bricks

# 메타데이터
title: Presentation Title
author: Your Name
info: |
  ## 설명
  여러 줄 지원

# 기능
mdc: true              # MDC 문법 활성화
monaco: dev            # Monaco 에디터 (dev/true/false)
lineNumbers: true      # 코드 줄번호
twoslash: true         # TypeScript 타입 정보
download: true         # PDF 다운로드 버튼

# 외관
colorSchema: auto      # auto, light, dark
transition: slide-left # 전역 트랜지션
highlighter: shiki

# 레이아웃
aspectRatio: 16/9
canvasWidth: 980

# 폰트
fonts:
  sans: Inter
  mono: Fira Code
  weights: '300,400,600,700'
  provider: google

# 드로잉
drawings:
  persist: false
  presenterOnly: false

# 내보내기
exportFilename: my-presentation
export:
  format: pdf
  withClicks: false
---

슬라이드별 설정

---
layout: center           # 레이아웃
background: /image.jpg   # 배경
class: text-white        # CSS 클래스
transition: fade         # 전역 설정 오버라이드
clicks: 5                # 클릭 수
hideInToc: true          # TOC에서 숨김
zoom: 0.8                # 콘텐츠 스케일
---

레이아웃 가이드

레이아웃 선택 체크리스트

2단 레이아웃 문법

two-cols:

---
layout: two-cols
---

# 왼쪽 제목

왼쪽 콘텐츠

::right::

# 오른쪽 제목

오른쪽 콘텐츠

two-cols-header:

---
layout: two-cols-header
---

# 공통 헤더

::left::

왼쪽 콘텐츠

::right::

오른쪽 콘텐츠

이미지 레이아웃

---
layout: image-right
image: /architecture.png
backgroundSize: contain  # cover | contain
class: my-content
---

# 시스템 아키텍처

다이어그램 설명

코드 블록 (Critical)

기본 문법

```typescript
const greeting: string = 'Hello, Slidev!'
```

줄 하이라이팅

```typescript {2,4}
const a = 1
const b = 2  // 하이라이트
const c = 3
const d = 4  // 하이라이트
```

클릭 기반 점진적 공개 (핵심 패턴)

```typescript {1|2-3|4-5|all}
// 클릭 1: 이 줄만
const step1 = 'First'
const step2 = 'Second'  // 클릭 2: 2-3줄
const step3 = 'Third'
const step4 = 'Fourth'  // 클릭 3: 4-5줄
// 클릭 4: 전체
```

패턴: {step1|step2|step3|all} - 각 |가 클릭

줄번호

```typescript {lines:true}
function factorial(n: number): number {
  if (n <= 1) return 1
  return n * factorial(n - 1)
}
```

```typescript {2,3}{lines:true,startLine:42}
// 42번 줄부터 시작
```

스크롤 가능 (긴 코드)

```typescript {*}{maxHeight:'200px'}
// 긴 코드 - 스크롤 가능
```

Monaco 에디터 (인터랙티브)

```typescript {monaco}
// 편집 가능한 코드
const x = 5
```

```typescript {monaco-run}
// 편집 + 실행 가능
console.log('실행됨!')
```

Shiki Magic Move (코드 애니메이션)

````md magic-move
```typescript
// Step 1: 초기 상태
const count = 1
```

```typescript
// Step 2: 줄 추가
const count = 1
const doubled = count * 2
```

```typescript
// Step 3: 리팩토링
function double(n: number) {
  return n * 2
}
const result = double(1)
```
````

애니메이션

v-click (단일 요소)

<v-click>클릭하면 나타남</v-click>

<div v-click>div도 가능</div>

<div v-click="3">3번째 클릭에 나타남</div>

v-clicks (목록 자동 적용)

<v-clicks>

- 첫 번째 (클릭 1)
- 두 번째 (클릭 2)
- 세 번째 (클릭 3)

</v-clicks>

v-clicks depth (중첩)

<v-clicks depth="2">

- 부모
  - 자식 1
  - 자식 2
- 부모 2

</v-clicks>

v-after (동시 표시)

<v-click>메인 콘텐츠</v-click>
<v-after>메인과 동시에 나타남</v-after>

클릭 범위 (표시/숨김 제어)

<!-- 클릭 2-4 동안만 표시 -->
<div v-click="[2, 5]">클릭 2, 3, 4에서만 보임</div>

<!-- 특정 클릭에 숨김 -->
<div v-click.hide="3">3번 클릭 후 사라짐</div>

상대 위치 지정

<div v-click>첫 번째 (클릭 1)</div>
<div v-click="'+2'">두 클릭 후 (클릭 3)</div>
<div v-click="'-1'">이전보다 한 클릭 전 (클릭 2)</div>

v-motion (이동 애니메이션)

<div
  v-motion
  :initial="{ x: -80, opacity: 0 }"
  :enter="{ x: 0, opacity: 1 }"
  :leave="{ x: 80, opacity: 0 }"
>
  왼쪽에서 들어와서 오른쪽으로 나감
</div>

클릭 기반 모션:

<div
  v-motion
  :initial="{ y: 100, opacity: 0 }"
  :enter="{ y: 50, opacity: 0.5 }"
  :click-1="{ y: 0, opacity: 1 }"
  :click-2="{ scale: 1.2 }"
>
  다단계 모션 애니메이션
</div>

슬라이드 트랜지션

---
transition: slide-left  # 전역
---

---
transition: fade        # 이 슬라이드만
---

옵션: slide-left, slide-right, slide-up, slide-down, fade, fade-out, view-transition, none

방향별 트랜지션:

---
transition: slide-left | slide-right
---

형식: 앞으로 | 뒤로

다이어그램

플랫폼 선택 가이드

Mermaid

```mermaid
graph TD
    A[시작] --> B{결정?}
    B -->|예| C[액션 1]
    B -->|아니오| D[액션 2]
    C --> E[끝]
    D --> E
```

```mermaid {theme: 'neutral', scale: 0.8}
sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: 요청
    S-->>C: 응답
```

PlantUML

```plantuml
@startuml
!theme plain

package "Node" {
    component [Device Plugin] as DP
    component [Kubelet] as K
}

package "Control Plane" {
    component [Scheduler] as S
}

DP -right-> K: gRPC
K -up-> S: Advertise

@enduml
```

다이어그램 설계 원칙

변환하지 말고 재설계하라:

• 각 플랫폼은 다른 "시각적 사고 방식"
• Mermaid: "이것이 어떻게 흐르는가?"
• PlantUML: "컴포넌트와 관계는?"
• Excalidraw: "이것을 어떻게 스케치하면 명확한가?"

인지 부하 제한:

• 다이어그램당 6-7개 요소 이하

발표자 노트

기본 문법

# 슬라이드 제목

청중에게 보이는 콘텐츠

<!--
발표자 노트 (발표자 모드에서만 표시)
- 포인트 1
- 포인트 2
-->

클릭 동기화 노트

<v-clicks>

- 포인트 A
- 포인트 B
- 포인트 C

</v-clicks>

<!--
[click] 포인트 A 상세 설명

[click] 포인트 B 설명

[click] 포인트 C 마무리
-->

비디오 발표용 노트 패턴

<!--
[HOOK] 문제 제기로 시작

잠시 멈춤

[click] 티저 공개 - 호기심 유발

[PAUSE] 시청자 흡수 시간

[TRANSITION] 다음 주제로 연결...
-->

스타일링

UnoCSS 유틸리티 (내장)

레이아웃:

• grid, flex, grid-cols-2, grid-cols-3
• gap-4, gap-8

간격:

• p-4, m-4, mt-8, px-2, py-1

타이포그래피:

• text-sm, text-xl, text-2xl, text-3xl
• font-bold, font-mono
• text-center, text-left

색상:

• text-blue-500, text-red-500
• bg-blue-500, bg-green-100
• bg-opacity-20, opacity-50

테두리:

• rounded, rounded-lg
• border, border-blue-500

절대 위치

<div class="abs-tr m-4">오른쪽 상단</div>
<div class="abs-tl m-4">왼쪽 상단</div>
<div class="abs-br m-4">오른쪽 하단</div>
<div class="abs-bl m-4">왼쪽 하단</div>

카드 패턴

<div class="p-4 rounded-lg bg-blue-500 bg-opacity-20 border border-blue-500">
카드 콘텐츠
</div>

스코프 스타일

# 제목

콘텐츠

<style scoped>
h1 {
  background: linear-gradient(90deg, #667eea, #764ba2);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}
</style>

v-mark 주석

손으로 그린 스타일 강조:

<span v-mark.underline>중요 개념</span>
<span v-mark.circle>핵심 용어</span>
<span v-mark.highlight="{ color: 'yellow' }">하이라이트</span>
<span v-mark.box>박스</span>
<span v-mark.strike>취소선</span>
<span v-mark.bracket>괄호</span>

클릭 트리거:

<span v-mark.underline="3">3번 클릭에 나타남</span>

아이콘 (Iconify)

<div class="i-carbon-logo-github text-4xl" />
<div class="i-mdi-heart text-red-500 text-3xl" />
<div class="i-heroicons-check-circle text-green-500" />

형식: i-{collection}-{icon-name}

브라우저: https://icones.js.org/

내보내기

브라우저 내보내기 (권장)

1. 개발 서버 시작: slidev
2. 네비게이션 바에서 "Export" 클릭
3. 또는 http://localhost:3030/export 방문

CLI 내보내기

# Playwright 먼저 설치
pnpm add -D playwright-chromium

# PDF 내보내기
slidev export
slidev export --output presentation.pdf
slidev export --with-clicks  # 애니메이션 포함
slidev export --dark         # 다크 모드
slidev export --range 1,4-8  # 특정 슬라이드

# 다른 형식
slidev export --format pptx  # PowerPoint
slidev export --format png   # PNG 이미지
slidev export --format md    # 마크다운 + PNG

내보내기 옵션

• --output - 파일명
• --format - 형식 (pdf, pptx, png, md)
• --with-clicks - 애니메이션 단계 포함
• --range - 특정 슬라이드 (예: 1,6-8,10)
• --dark - 다크 테마
• --timeout - 타임아웃 증가
• --wait - 내보내기 전 대기 시간

트러블슈팅

슬라이드 업데이트 안 됨

# 캐시 강제 새로고침
slidev --force

# .slidev 폴더 삭제
rm -rf .slidev && slidev

레이아웃 찾을 수 없음

• 레이아웃 이름 철자 확인 (대소문자 구분)
• 테마에 해당 레이아웃 포함 여부 확인
• 커스텀 레이아웃: ./layouts/layout-name.vue

이미지 로드 안 됨

• 경로가 /로 시작해야 함 (public 폴더용)
• 파일이 public/ 디렉토리에 있는지 확인
• 브라우저 콘솔에서 404 확인

코드 하이라이팅 안 됨

• 언어 명시: ```typescript (``` 아님)
• 캐시 클리어: slidev --force

Monaco 작동 안 함

• headmatter에서 활성화: monaco: 'dev' 또는 monaco: true
• 캐시 클리어
• 브라우저 콘솔 에러 확인

내보내기 실패/중단

# Playwright 설치
pnpm add -D playwright-chromium

# 타임아웃 증가
slidev export --timeout 60000

# 대기 시간 추가
slidev export --wait 2000

진단 명령어

# 버전 확인
pnpm list @slidev/cli

# 모든 캐시 클리어
rm -rf .slidev node_modules/.vite
pnpm install
slidev --force

# 상세 로깅
slidev --log debug

워크플로우 체크리스트

새 프레젠테이션 생성

1. 프로젝트 생성: pnpm create slidev
2. .markdownlint.json 생성 (필수!)
3. frontmatter 설정 (테마, 폰트, 설정)
4. 접근성 스타일 추가
5. 슬라이드 작성
6. 발표자 노트 작성
7. 개발 서버로 미리보기: slidev
8. 내보내기: slidev export

슬라이드 작성 시

1. 슬라이드당 하나의 아이디어
2. 제목은 주장 형태
3. 50단어 미만
4. 6개 이하 요소
5. 점진적 공개 사용 (v-clicks)
6. 발표자 노트 작성
7. 접근성 확인 (폰트, 대비)

CLI 명령어 요약

# 개발
pnpm create slidev          # 새 프로젝트
slidev                      # 개발 서버 시작
slidev slides.md            # 특정 파일
slidev --port 8080          # 포트 지정
slidev --force              # 캐시 클리어

# 빌드
slidev build                # 프로덕션 빌드
slidev build --base /sub/   # 서브 경로용

# 내보내기
slidev export               # PDF
slidev export --format pptx # PowerPoint
slidev export --format png  # 이미지
slidev export --with-clicks # 애니메이션 포함

# 포맷팅
slidev format               # 슬라이드 포맷

키보드 단축키

참조 문서

• references/layouts-reference.md - 17개 레이아웃 상세 가이드
• references/slide-templates.md - 재사용 가능한 슬라이드 템플릿
• references/troubleshooting.md - 문제 해결 가이드
• references/diagram-design.md - 다이어그램 설계 철학

외부 리소스

• 공식 문서: https://sli.dev
• 테마 갤러리: https://sli.dev/resources/theme-gallery
• 애드온 갤러리: https://sli.dev/resources/addon-gallery
• 아이콘 브라우저: https://icones.js.org
• GitHub: https://github.com/slidevjs/slidev