# Slidev 교안 슬라이드

Slidev로 발표 자료를 만들고 자동 생성하는 방법을 정리합니다.

원본 URL: https://abc.noco.kr/cases/slides

강의 내용이 바뀔 때마다 슬라이드를 한 장씩 고치면 같은 일을 여러 번 하게 된다. [Slidev](/glossary#slidev)로 교안을 텍스트로 관리하고, [에이전트](/glossary#agent)에 생성·수정·확인을 맡기면 내용에 집중할 시간을 확보할 수 있다.

기준일: 2026-09-30.

## 어떤 문제를 풀었나

수업 자료는 한 번 만들고 끝나지 않는다. 실습 명령이 바뀌고, 설명이 부족한 부분이 드러나고, 수강생의 질문이 쌓인다.

발표 자료와 실습 안내가 따로 있으면 한쪽만 고치기 쉽다. 교안에는 새 명령이 있지만 슬라이드에는 이전 명령이 남는 식이다.

여기서는 다음과 같은 수업 준비 상황을 예시로 삼는다.

- 실습 안내를 바탕으로 발표 자료 초안을 만든다.
- 질문이 많았던 부분에 설명과 그림을 추가한다.
- 명령 변경이 생기면 관련 슬라이드만 수정한다.
- 브라우저에서 확인한 뒤 배포용 파일을 만든다.

강사가 결정할 것은 수업의 목표와 설명 순서다. 에이전트에는 반복되는 편집과 렌더링 확인을 맡긴다.

첫 작업부터 멋진 디자인을 요구할 필요는 없다. 내용과 순서가 맞는지 확인한 뒤 화면을 다듬는 편이 수정 범위를 좁히기 쉽다.

## 무엇을 어떻게 연결하나

교안과 실습 파일을 입력으로 두고, Slidev 프로젝트의 `slides.md`를 수정 대상으로 둔다. 생성된 화면과 내보낸 파일은 별도로 확인한다.

[Mermaid](/glossary#mermaid)는 관계를 텍스트로 표현할 때 쓴다. 아래 그림은 이 사례에서 사용하는 작업 흐름이다.

```mermaid
flowchart LR
  A[교안과 실습 안내] --> B[에이전트]
  R[수업 목표와 수정 범위] --> B
  B --> C[slides.md]
  C --> D[Slidev 브라우저 화면]
  D --> E[강사의 내용 확인]
  E -->|수정 요청| B
  E --> F[PDF 또는 PPTX 내보내기]
  F --> G[최종 파일 확인]
```

이 구성에서 교안은 내용의 기준이고, `slides.md`는 발표 자료의 편집 원고다. 내보낸 PPTX만 수정하면 이후 다시 생성할 때 그 수정이 사라질 수 있다.

파일 역할을 미리 적어 두면 요청도 구체적으로 할 수 있다.

| 파일 또는 자료 | 역할 | 수정할 때 지킬 것 |
| --- | --- | --- |
| 교안과 실습 안내 | 설명과 명령의 기준 | 실습 내용과 맞춘다 |
| `slides.md` | 발표 순서와 화면 구성 | 한 장의 목적을 분명히 한다 |
| 발표자 노트 | 말로 보충할 설명 | 화면 본문과 구분한다 |
| PDF·PPTX | 공유하거나 발표할 결과물 | 직접 열어 확인한다 |

## 프로젝트 준비

새 교안은 별도 폴더에서 시작한다. 기존 문서 사이트나 다른 수업 자료 폴더에서 설치 명령을 실행하지 않는다.

설치 순서와 실행 환경은 [Slidev 공식 시작 안내](https://sli.dev/guide/)에서 확인할 수 있다. 프로젝트 생성 명령은 다음과 같다.

```sh
pnpm create slidev
```

생성 도중 선택한 프로젝트 폴더로 이동하고, 안내에 따라 의존성을 설치한다. 이후 예시 명령은 그 폴더에서 실행한다.

```sh
pnpm install
pnpm dev
```

처음에는 생성된 예제를 그대로 열어 본다. 예제가 보이는 상태를 확인하고 나서 수업 내용을 넣으면 설치 문제와 내용 문제를 구분하기 쉽다.

사용한 Node.js·pnpm·Slidev 버전과 잠금 파일을 남긴다. 다른 컴퓨터에서 다시 만들 때는 이 기록을 먼저 확인한다.

## 쓸 만한 요청 만들기

### 목차부터 초안 요청

다음은 처음 자료를 만드는 요청 예시다. 경로와 분량은 수업에 맞게 바꾼다.

```text
lesson.md와 exercises/를 읽고 45분 수업의 발표 자료 목차를 제안해 줘.
대상은 터미널을 처음 쓰는 수강생이다.
학습 목표는 명령 실행, 결과 확인, 실패 원인 찾기 세 가지다.

아직 파일을 수정하지 말고, 슬라이드별 제목과 목적을 표로 보여 줘.
설명 뒤에 짧은 실습을 넣고, 실습 명령은 exercises/와 일치시켜 줘.
확인할 수 없는 명령이나 제품 기능은 추가하지 마.
```

목차를 보고 빠진 내용과 불필요한 설명을 고른다. 화면을 먼저 만들면 내용 수정과 디자인 수정이 한꺼번에 발생하기 쉽다.

### 승인 목차의 슬라이드화

```text
승인한 목차대로 slides.md만 수정해 줘.
한 장에는 핵심 설명 하나와 짧은 예시 하나를 담아 줘.
화면에 넣기 긴 설명은 발표자 노트로 옮겨 줘.
실습 명령은 교안의 명령을 그대로 사용해 줘.

기존 테마와 설정은 유지하고 새 패키지는 추가하지 마.
수정 뒤 변경한 슬라이드와 검증 결과를 알려 줘.
```

한 장에 들어갈 글의 양은 실제 화면을 보면서 조정한다. 글자 수만 맞춰도 긴 경로나 코드 때문에 줄이 넘칠 수 있다.

### 수정 요청 범위 좁히기

```text
설치 설명과 첫 실습 사이에 결과 확인 슬라이드 한 장을 추가해 줘.
정상 출력과 오류 출력을 나란히 비교하고,
각각 수강생이 확인할 지점을 한 문장으로 적어 줘.

기존 실습 명령과 다른 슬라이드 순서는 바꾸지 마.
오류 출력은 제공한 로그에서만 가져와 줘.
```

“전체를 더 좋게”보다 어느 부분에 무엇을 넣을지 정한 요청이 검토하기 쉽다. 추가할 내용이 교안에 없다면 먼저 내용을 확인한다.

## 원고에서 최종 파일까지

### 1. 작은 슬라이드 묶음

Slidev의 구분자와 발표자 노트 문법은 [공식 문법 안내](https://sli.dev/guide/syntax)에서 확인할 수 있다. 아래는 설명·실습·확인을 나누는 원고 예시다.

````markdown
---
title: 명령 실행과 결과 확인
---

# 명령 실행과 결과 확인

명령을 실행한 뒤 출력과 종료 상태를 확인한다.

---

# 직접 실행해 보기

실습 폴더에서 교안에 있는 명령을 실행한다.

<!-- 여기서 실행 위치와 예상 결과를 먼저 보여 준다. -->

---

# 결과를 확인하기

- 예상한 파일이 생겼는가?
- 오류 메시지가 남았는가?
- 실행 위치가 맞는가?
````

이 정도만 만들어도 설명이 긴지, 실습 앞에 필요한 안내가 빠졌는지 확인할 수 있다.

### 2. 내용·화면 분리 검토

먼저 명령·경로·용어를 교안과 대조한다. 그다음 브라우저에서 제목, 코드, 표가 잘리는지 확인한다.

[룰](/glossary#rules)이나 [스킬](/glossary#skills)에 확인 절차를 남겨 두면 수정할 때마다 같은 기준을 사용할 수 있다.

렌더링 성공만으로 발표 자료가 완성되지는 않는다. 강사가 실제로 설명할 순서대로 넘겨 보고, 실습으로 넘어가는 위치가 자연스러운지도 확인한다.

### 3. 형식별 내보내기

내보내기 명령과 제한은 [Slidev 공식 내보내기 안내](https://sli.dev/guide/exporting)에서 확인할 수 있다. CLI로 PDF·PPTX를 만들 때는 프로젝트에 렌더링 의존성을 설치한다.

```sh
pnpm add -D playwright-chromium
pnpm exec slidev export
pnpm exec slidev export --format pptx
```

일반 `pptx` 형식은 슬라이드를 이미지로 내보낸다. 발표자 노트는 전달되지만 화면의 글을 PowerPoint 텍스트처럼 선택해 고치는 방식은 아니다.

편집 가능한 결과가 필요하면 같은 공식 안내의 `pptx-editable` 형식을 확인한다. 텍스트와 도형을 편집 가능하게 내보내지만 그림으로 남는 요소와 슬라이드별 이미지 전환이 있어 결과 확인이 필요하다.

```sh
pnpm exec slidev export --format pptx-editable
```

형식을 정할 때는 받는 사람이 발표만 할지, 내용을 직접 고칠지도 묻는다. 브라우저 화면과 내보낸 파일은 서로 다른 결과물로 취급한다.

### 4. 내보낸 파일 확인

PDF에서는 코드와 표가 잘리지 않는지 확인한다. PPTX는 실제 발표 환경에서 글꼴, 줄바꿈, 그림 위치를 확인한다.

브라우저에서 동작하는 상호작용이 내보낸 파일에서도 그대로 동작한다고 가정하지 않는다. 필요한 기능이 있으면 브라우저 발표와 파일 배포의 용도를 나눈다.

확인이 끝나면 원고, 잠금 파일, 최종 결과물을 함께 보관한다. 수정 요청에는 이전 결과물보다 원고의 어느 부분을 바꿀지 적는다.

## 자주 막히는 지점과 주의점

### 실행과 내용의 불일치

도구는 문법상 문제없는 슬라이드를 만들 수 있어도 수업의 설명 순서를 보장하지 않는다. 교안과 다른 명령, 생략된 준비 과정, 근거 없는 기능 설명을 먼저 찾는다.

오류가 있으면 관련 슬라이드와 교안 위치를 함께 알려 준다. 범위를 좁혀 고친 뒤 같은 확인 절차를 다시 실행한다.

### 과도한 화면 텍스트

글자 크기부터 줄이지 않는다. 한 장의 목적을 정하고, 설명을 다음 슬라이드나 발표자 노트로 나눈다.

실습 명령은 그대로 두고 주변 설명부터 줄인다. 긴 명령을 보기 좋게 바꾸다가 실행 가능한 명령이 달라지지 않도록 한다.

### 내보내기 실패

프로젝트 위치와 의존성 설치 여부를 먼저 확인한다. 브라우저 렌더링 단계에서 실패하면 마지막 오류와 실패한 슬라이드를 기록한다.

타임아웃 값을 무조건 늘리기 전에 외부 이미지나 글꼴 로딩이 끝나는지 확인한다. 일부 슬라이드만 만들어 문제 범위를 줄이는 방법도 쓸 수 있다.

### 여러 곳의 중복 수정

설명과 실습의 기준 파일을 정한다. 공통 명령이 바뀌면 기준 파일을 수정한 뒤 슬라이드의 해당 부분을 갱신하도록 요청한다.

수업이 끝난 뒤에는 질문이 많았던 부분을 짧게 남긴다. 그 기록을 바탕으로 다음 수정 범위를 정하면 자료 전체를 다시 만들지 않아도 된다.