Slidev Mastery

What this skill does

# Slidev Mastery

Slidev is a presentation framework for developers that uses markdown with Vue components. Create beautiful, interactive slides using familiar syntax with powerful features like live coding, diagrams, and animations.

**Evidence-based design**: This skill incorporates research-based best practices for accessible, effective presentations. See `references/presentation-best-practices.md` for full guidelines.

## Core Concepts

### Slide Separation

Separate slides with `---` on its own line:

```markdown
# First Slide

Content here

---

# Second Slide

More content
```

### Importing Slides from External Files

You can split your presentation into multiple markdown files using the `src` frontmatter option. This allows for better organization and reusability:

```markdown
# Normal slide

---
src: ./slides/introduction.md
---

---
# Another normal slide

---
src: ./slides/conclusion.md
---
```

**Benefits of modular slide structure:**
- **Stable identity:** Use meaningful filenames (e.g., `microservices-benefits.md`) instead of numbers
- **Easy reordering:** Move `src` includes in master file without renaming files
- **Independent editing:** Edit individual slide files separately
- **Better collaboration:** Team members can work on different slides simultaneously
- **Version control:** Meaningful file names in git diffs

**Example structure:**
```
presentation/
├── slides.md                      # Master file with includes
├── slides/
│   ├── 01-title.md                # Slide 1: Title
│   ├── 02-hook.md                 # Slide 2: Opening hook
│   ├── 03-problem-statement.md    # Slide 3: Problem introduction
│   ├── 04-architecture-overview.md # Slide 4: Architecture slide
│   ├── 18-conclusion.md           # Conclusion
│   └── 19-questions.md            # Q&A
└── public/images/
```

**File naming:** Individual slides use numeric prefix (01-, 02-, etc.) plus descriptive name for easy ordering in directory listings while maintaining meaningful names.

**Master file example with slide number comments:**
```markdown
---
theme: default
title: My Presentation
---

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

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

---
src: ./slides/03-problem-statement.md
---
<!-- Slide 3: Problem Statement -->
```

**Note:** Comments must come AFTER the closing `---` (not inside frontmatter block) per Slidev specs.

**Frontmatter merging:** You can override frontmatter from external files:
```markdown
---
src: ./slides/content.md
layout: two-cols  # Overrides layout in content.md
---
```

### Frontmatter Configuration

Configure presentation globally in frontmatter at the top of `slides.md`:

```yaml
---
theme: default
background: https://source.unsplash.com/collection/94734566/1920x1080
class: text-center
highlighter: shiki
lineNumbers: false
drawings:
  persist: false
transition: slide-left
title: Welcome to Slidev
---
```

**Key frontmatter fields:**
- `theme`: Visual theme (default, seriph, apple-basic, etc.)
- `background`: Global background image or color
- `highlighter`: Code highlighting engine (shiki or prism)
- `lineNumbers`: Show line numbers in code blocks
- `transition`: Slide transition effect
- `title`: Presentation title for metadata

### Per-Slide Frontmatter

Configure individual slides with frontmatter after `---`:

```markdown
---
layout: center
background: './images/background.jpg'
class: 'text-white'
---

# Centered Slide

With custom background
```

## Layouts

Slidev provides built-in layouts for different slide types:

### Common Layouts

**`default`** - Standard layout with title and content:
```markdown
# Title

Content here
```

**`center`** - Centered content:
```markdown
---
layout: center
---

# Centered Title
```

**`cover`** - Cover slide for presentation start:
```markdown
---
layout: cover
background: './bg.jpg'
---

# Presentation Title

Subtitle or author
```

**`intro`** - Introduction slide:
```markdown
---
layout: intro
---

# Topic

Brief description
```

**`image-right`** - Content on left, image on right:
```markdown
---
layout: image-right
image: './diagram.png'
---

# Content

Text goes here
```

**`image-left`** - Image on left, content on right:
```markdown
---
layout: image-left
image: './photo.jpg'
---

# Content

Text goes here
```

**`two-cols`** - Two column layout:
```markdown
---
layout: two-cols
---

# Left Column

Content for left

::right::

# Right Column

Content for right
```

**`quote`** - Large quote display:
```markdown
---
layout: quote
---

# "Innovation distinguishes between a leader and a follower."

Steve Jobs
```

**`fact`** - Emphasize key fact or statistic:
```markdown
---
layout: fact
---

# 95%

User satisfaction rate
```

## Code Highlighting

### Basic Code Blocks

```markdown
\```python
def hello():
    print("Hello, World!")
\```
```

### Line Highlighting

Highlight specific lines with `{line-numbers}`:

```markdown
\```python {2-3}
def process():
    important_line()
    another_important()
    return result
\```
```

### Line Numbers

Enable line numbers for a code block:

```markdown
\```python {1|2|3} {lines:true}
first_line()
second_line()
third_line()
\```
```

### Monaco Editor

Enable live code editing with Monaco:

```markdown
\```python {monaco}
def editable():
    return "Users can edit this code"
\```
```

## Animations and Clicks

### Click Animations

Reveal content incrementally with `v-click`:

```markdown
- First point
- <v-click>Second point (appears on click)</v-click>
- <v-click>Third point (appears on next click)</v-click>
```

### After Clicks

Show content after specific click:

```markdown
<div v-after="2">
  Appears after 2 clicks
</div>
```

### Click Counting

Use click counters for complex animations:

```markdown
<div v-click="1">First</div>
<div v-click="2">Second</div>
<div v-click="3">Third</div>
```

## Mermaid Diagrams

Embed mermaid diagrams directly:

```markdown
\```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
\```
```

**Supported diagram types:**
- Flowchart: `graph LR`, `graph TD`
- Sequence: `sequenceDiagram`
- Class: `classDiagram`
- State: `stateDiagram-v2`
- ER: `erDiagram`
- Gantt: `gantt`

### Custom Theme

Apply custom colors to mermaid diagrams:

```markdown
\```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#3b82f6'}}}%%
graph TD
    A[Blue themed]
\```
```

## Images and Media

### Images

```markdown
![Alt text](./path/to/image.jpg)
```

With custom size:

```markdown
<img src="./image.jpg" class="w-50 mx-auto" />
```

### Background Images

Per-slide background:

```markdown
---
background: './images/slide-bg.jpg'
---
```

## Presenter Notes

Add notes visible only in presenter mode:

```markdown
# Slide Title

Content visible to audience

<!--
These are presenter notes
Only visible in presenter mode
Press 'p' to toggle presenter view
-->
```

## Components

### Built-in Components

**Arrows**:
```markdown
<Arrow x1="100" y1="100" x2="200" y2="200" />
```

**YouTube**:
```markdown
<Youtube id="video-id" width="500" height="300" />
```

**Tweet**:
```markdown
<Tweet id="tweet-id" />
```

### Custom Components

Create reusable Vue components in `components/` directory:

```vue
<!-- components/CustomButton.vue -->
<template>
  <button class="custom-btn">
    <slot />
  </button>
</template>

<style scoped>
.custom-btn {
  background: #3b82f6;
  color: white;
  padding: 1rem 2rem;
  border-radius: 0.5rem;
}
</style>
```

Use in slides:

```markdown
<CustomButton>Click me</CustomButton>
```

## Themes

### Using Themes

Set in frontmatter:

```yaml
---
theme: seriph
---
```

**Popular themes:**
- `default` - Clean, minimal
- `seriph` - Elegant serif fonts
- `apple-basic` - Apple keynote style
- `shibainu` - Playful, colorful
- `bricks` - Modern, structured

### Custom Styling

Add custom CSS in frontmatter or separate `style.css`:

```markdown
---
---

<style>
h1 {
  color: #3b82f6;
}

.custom-class {
  background: linea