create-slidev-presentation

Original source / Raw SKILL.md

---
name: create-slidev-presentation
description: This skill should be used when asked to create or edit Slidev (sli.dev) presentation slide decks.
---

# Slidev

## Overview

Enable creation and editing of high-quality Slidev presentations. Slidev is a web-based presentation framework that uses Markdown with Vue 3 components, providing features like live code editing, syntax highlighting, animations, and export to multiple formats.

**Key capabilities**:
- Create presentations from markdown with YAML configuration
- Use 17 built-in layouts plus custom layouts
- Add click animations, transitions, and motion effects
- Embed live code editors (Monaco) with TypeScript support
- Include diagrams (Mermaid, PlantUML), LaTeX math, and media
- Export to PDF, PPTX, PNG, or static web application

**Requirements**: Node.js >= 24.0.0

## Quick Start

### Creating a New Presentation

```bash
# Initialize project
pnpm create slidev

# Or with specific entry file
pnpm create slidev my-slides

# Start development server
cd my-slides
pnpm run dev
```

### Minimal Presentation Structure

```markdown
---
theme: default
title: My Presentation
---

# Welcome

Introduction slide

---

# Second Slide

Content here

---
layout: end
---

# Thank You
```

**Slide separator**: Three dashes (`---`) padded with new lines

## Creating Presentations

### Structure Decision Tree

**Is this a new presentation?**
- Yes → Use template from `assets/slide-templates.md` or `assets/example-configurations.md`
- No → See "Editing Presentations" section

**What type of presentation?**
- **Business/Professional** → Use `seriph` theme, simple transitions
- **Technical/Code-heavy** → Enable `monaco`, `lineNumbers`, use code templates
- **Conference/Workshop** → Enable `drawings`, `record`, `presenter` mode
- **Educational** → Use clear layouts, diagrams, progressive disclosure
- **Design-focused** → Minimalist theme, `fade` transitions, large typography

### Configuration Approach

Start with minimal headmatter, add features as needed:

**Step 1 - Minimal** (always include):
```yaml
---
theme: default
title: Presentation Title
---
```

**Step 2 - Add features** (based on content):
```yaml
---
theme: seriph
title: Presentation Title
author: Your Name
mdc: true
lineNumbers: true  # For code
monaco: dev        # For live code
transition: slide-left
---
```

**Step 3 - Optimize** (for specific use case):
- Code presentations: Add `twoslash`, higher `canvasWidth` (1200)
- Media-heavy: Set `aspectRatio: 16/9`, optimize fonts
- Export-focused: Configure `export` options, set `exportFilename`

### Layout Selection

Use appropriate layout for each slide's purpose:

| Slide Purpose    | Layout             | Example                   |
|------------------|--------------------|---------------------------|
| Title slide      | `cover`            | Opening slide             |
| Section divider  | `section`          | New topic                 |
| Standard content | `default`          | Bullet points, text       |
| Centred content  | `center`           | Short quotes              |
| Two columns      | `two-cols`         | Comparisons               |
| Image + text     | `image-left/right` | Diagrams with explanation |
| Big number/stat  | `fact`             | Key metrics               |
| Quote            | `quote`            | Testimonials              |
| Final slide      | `end`              | Thank you, Q&A            |

Specify layout in per-slide frontmatter:
```yaml
---
layout: two-cols
---
```

**Reference**: `references/layouts-reference.md` for all 17 layouts with examples

### Component Usage

Built-in components for common needs:

**Click animations**:
```markdown
<v-clicks>

- Item 1
- Item 2
- Item 3

</v-clicks>
```

**Media embedding**:
```markdown
<Youtube id="dQw4w9WgXcQ" />
<Tweet id="1234567890" />
```

**Navigation**:
```markdown
<Link to="42">Go to slide 42</Link>
<Toc minDepth="1" maxDepth="2" />
```

**Reference**: `references/components-reference.md` for complete component library

### Code Presentation

**Basic code block**:
````markdown
```typescript
const greeting: string = 'Hello, Slidev!'
console.log(greeting)
```
````

**With line highlighting** (incremental):
````markdown
```ts {1|3-4|all}
const step1 = 'First'
// Highlight line 1
const step2 = 'Second'
const step3 = 'Third'
// Then highlight lines 3-4
// Finally highlight all
```
````

**Interactive editor**:
````markdown
```ts {monaco-run}
console.log('Runs in browser!')
```
````

**Best practices**:
1. Always specify language for syntax highlighting
2. Use incremental highlighting to guide attention
3. Keep code blocks under 20 lines (use `{maxHeight:'200px'}` if longer)
4. Enable `lineNumbers: true` for code-heavy presentations

### Animations

**Progressive disclosure** (most common):
```markdown
<v-clicks>

- Point 1
- Point 2
- Point 3

</v-clicks>
```

**Element-level control**:
```markdown
<div v-click>Appears on click 1</div>
<div v-click>Appears on click 2</div>
<div v-click="3">Appears on click 3</div>
```

**Motion animations**:
```markdown
<div
  v-motion
  :initial="{ x: -80, opacity: 0 }"
  :enter="{ x: 0, opacity: 1 }"
>
  Animated entrance
</div>
```

**Slide transitions**:
```yaml
---
transition: slide-left
---
```

Options: `fade`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `view-transition`

## Editing Presentations

### Modification Strategy

**Step 1 - Read and understand**:
1. Read `slides.md` to understand structure
2. Identify headmatter (first frontmatter block)
3. Note layouts and components used

**Step 2 - Make targeted changes**:
- **Add slides**: Insert `---` separator and new content
- **Modify content**: Edit markdown between separators
- **Change layouts**: Update per-slide frontmatter
- **Adjust config**: Modify headmatter or create `slidev.config.ts`

**Step 3 - Test changes**:
```bash
slidev  # Verify in dev server
```

### Common Editing Tasks

**Add slide after specific slide**:
1. Find target slide content
2. Add separator (`---`) after it
3. Add new slide content

**Change slide layout**:
```markdown
---
layout: two-cols  # Change this
---
```

**Add click animations to list**:
```markdown
<v-clicks>

- Existing item 1
- Existing item 2

</v-clicks>
```

**Enable feature globally**:
Update headmatter:
```yaml
---
# Add/update these
monaco: dev
lineNumbers: true
---
```

**Split long presentation**:
Create `pages/section1.md`, then in main `slides.md`:
```markdown
---
src: ./pages/section1.md
---
```

## Common Patterns

Use pre-built templates from `assets/slide-templates.md`:

**Title slide pattern**:
```markdown
---
layout: cover
background: /cover.jpg
class: text-center
---

# Title

## Subtitle

Author · Date
```

**Code demo pattern**:
````markdown
---
layout: two-cols
---

```ts {monaco-run}
// Interactive code
```

::right::

# Explanation

- Point 1
- Point 2
````

**Comparison pattern**:
```markdown
---
layout: two-cols
---

# Before

Old approach

::right::

# After

New approach
```

**Section divider pattern**:
```markdown
---
layout: section
background: linear-gradient(to right, #667eea, #764ba2)
class: text-white
---

# Part 2: Implementation
```

**Complete examples**: See `assets/example-configurations.md` for full presentation templates

## Export & Build

### Export to PDF

```bash
# Basic export
slidev export

# With options
slidev export --output presentation.pdf
slidev export --with-clicks  # Include animations
slidev export --dark         # Dark mode
slidev export --range 1,4-8  # Specific slides
```

**Prerequisites**: Install playwright-chromium
```bash
pnpm add -D playwright-chromium
```

### Export to Other Formats

```bash
slidev export --format pptx   # PowerPoint
slidev export --format png    # PNG images
slidev export --format md     # Markdown with PNGs
```

### Build Static Site

```bash
slidev build
slidev build --base /slides/  # For subdirectory hosting
```

Deploy `dist/` directory to static hosting (Netlify, Vercel, GitHub Pages).

## Configuration Reference

### Essential Headmatter Options

```yaml
---
# Theme
theme: seriph  # or: default, apple-basic, carbon, dracula, nord, etc.

# Metadata
title: Presentation Title
author: Your Name
info: |
  ## Description
  Multi-line supported

# Features
mdc: true              # Enable MDC syntax
monaco: dev            # Enable Monaco editor
lineNumbers: true      # Line numbers in code
twoslash: true         # TypeScript type info
download: true         # PDF download button

# Appearance
colorSchema: auto      # auto, light, or dark
transition: slide-left # Global transition

# Layout
aspectRatio: 16/9
canvasWidth: 980

# Fonts
fonts:
  sans: Inter
  mono: JetBrains Mono
  weights: '300,400,600,700'
  provider: google

# Export
exportFilename: my-presentation
export:
  format: pdf
  withClicks: false
  dark: false
---
```

**Complete reference**: See `references/configuration-reference.md`

### Per-Slide Frontmatter

```yaml
---
layout: center           # Slide layout
background: /image.jpg   # Background image
class: text-white        # CSS classes
transition: fade         # Override global
clicks: 5                # Number of clicks
hideInToc: true         # Hide from TOC
zoom: 0.8               # Scale content
routeAlias: solutions   # Navigation alias
---
```

## Troubleshooting

### Common Issues

**Slides not updating**:
```bash
slidev --force  # Clear cache
```

**Layout not found**:
- Check layout name spelling (case-sensitive)
- Verify theme includes layout
- Create custom layout in `./layouts/`

**Code not highlighting**:
- Specify language: ` ```typescript ` not ` ``` `
- Check for syntax errors
- Clear cache: `slidev --force`

**Export fails or hangs**:
```bash
pnpm add -D playwright-chromium  # Install first
slidev export --timeout 60000    # Increase timeout
slidev export --wait 2000         # Add wait time
```

**Monaco not working**:
- Set `monaco: 'dev'` or `monaco: true` in headmatter
- Clear cache
- Check browser console for errors

**Images not loading**:
- Path must start with `/` for public folder
- Verify file in `public/` directory
- Check browser console for 404s

**Complete guide**: See `references/troubleshooting.md`

## Best Practices

### Content Organisation
1. **One idea per slide** - Don't overcrowd
2. **6x6 rule** - Max 6 lines, 6 words per line
3. **Visual hierarchy** - Use heading levels consistently
4. **Progressive disclosure** - Use `<v-clicks>` for lists
5. **Consistent styling** - Stick to theme

### Code Presentation
1. **Specify language** - Always enable syntax highlighting
2. **Line highlighting** - Guide attention: `{1|3-5|all}`
3. **Keep it short** - Under 20 lines per block
4. **Use Monaco** - For interactive demos
5. **Font size** - Ensure readability (use `zoom` if needed)

### Performance
1. **Optimise images** - Compress, use WebP
2. **Lazy load** - `preload: false` on heavy slides
3. **Limit animations** - Balance engagement vs. performance
4. **Local assets** - Use `/public` folder
5. **Disable unused features** - `monaco: false` if not needed

### Accessibility
1. **Colour contrast** - Minimum 4.5:1 ratio
2. **Alt text** - Describe images
3. **Font size** - Minimum 24pt body text
4. **Test keyboard navigation** - Arrow keys should work
5. **Avoid flashing** - No rapid animations (<3/second)

## Resources

This skill includes comprehensive documentation:

### `references/`
- **layouts-reference.md** - All 17 built-in layouts with examples
- **components-reference.md** - Complete component library and custom patterns
- **configuration-reference.md** - All configuration options and setup files
- **troubleshooting.md** - Common issues and solutions

### `assets/`
- **slide-templates.md** - Ready-to-use templates for common slide types
- **example-configurations.md** - Complete example configurations for different use cases

### Official Documentation
- Website: https://sli.dev
- Docs: https://sli.dev/guide/
- GitHub: https://github.com/slidevjs/slidev
- Themes: https://sli.dev/resources/theme-gallery

## Workflow Example

**User request**: "Create a technical presentation about TypeScript best practices"

**Step 1**: Choose template from `assets/example-configurations.md` → "Technical/Code-Heavy Presentation"

**Step 2**: Create `slides.md` with appropriate headmatter:
```yaml
---
theme: default
title: TypeScript Best Practices
author: Developer Name
monaco: dev
lineNumbers: true
twoslash: true
---
```

**Step 3**: Add slides using templates from `assets/slide-templates.md`:
- Cover slide
- Section dividers
- Code demonstration slides
- Comparison slides
- End slide

**Step 4**: Start dev server to preview:
```bash
slidev
```

**Step 5**: Export when ready:
```bash
slidev export --format pdf
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### assets/slide-templates.md

```markdown
# Slidev Slide Templates

Ready-to-use slide templates for common presentation patterns.

## Title Slide Templates

### Standard Title Slide
```markdown
---
layout: cover
background: /cover-image.jpg
class: text-center
---

# Presentation Title

## Subtitle or Tagline

Your Name · Date/Event
```

### Minimal Title Slide
```markdown
---
layout: cover
class: text-center
---

# Presentation Title

By Your Name
```

### Gradient Background Title
```markdown
---
layout: cover
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%)
class: text-center text-white
---

# Modern Presentation

## Innovative Solutions

Team Name · Q1 2025
```

## Section Divider Templates

### Simple Section Divider
```markdown
---
layout: section
---

# Part 2: Implementation
```

### Styled Section Divider
```markdown
---
layout: section
background: linear-gradient(to right, #4facfe, #00f2fe)
class: text-white
---

# Technical Deep Dive

Advanced concepts and patterns
```

### Numbered Section
```markdown
---
layout: section
background: /section-bg.jpg
class: text-white
---

# 03

Performance Optimisation
```

## Content Slide Templates

### Bullet Points
```markdown
---
layout: default
---

# Key Features

<v-clicks>

- Feature 1: Fast and responsive
- Feature 2: Easy to use
- Feature 3: Highly customizable
- Feature 4: Open source

</v-clicks>
```

### Two-Column Comparison
```markdown
---
layout: two-cols
---

# Traditional Approach

- Manual processes
- Time-consuming
- Error-prone
- Limited scalability

::right::

# Our Solution

- Automated workflows
- Instant results
- Reliable
- Infinitely scalable
```

### Problem-Solution
```markdown
---
layout: two-cols
---

# The Problem

Current systems struggle with:

- Performance bottlenecks
- Complex configuration
- Poor developer experience
- Limited flexibility

::right::

# The Solution

Our approach provides:

- 10x faster processing
- Zero-config setup
- Intuitive API
- Plug-and-play architecture
```

## Code Demonstration Templates

### Simple Code Block
````markdown
---
layout: default
---

# Example Code

```typescript {all|1-3|5-7|all}
interface User {
  id: number
  name: string
}

const user: User = {
  id: 1,
  name: 'Alice'
}
```
````

### Side-by-Side Code Comparison
````markdown
---
layout: two-cols
---

# Before

```javascript
var users = []
for (var i = 0; i < data.length; i++) {
  users.push(data[i].name)
}
```

::right::

# After

```javascript
const users = data.map(u => u.name)
```
````

### Live Code Editor
````markdown
---
layout: two-cols
---

# Interactive Demo

```typescript {monaco-run}{height:300px}
interface Product {
  name: string
  price: number
}

const products: Product[] = [
  { name: 'Laptop', price: 999 },
  { name: 'Mouse', price: 29 }
]

const total = products.reduce(
  (sum, p) => sum + p.price,
  0
)

console.log(`Total: $${total}`)
```

::right::

# Features

- Full TypeScript support
- IntelliSense
- Run code in browser
- Instant feedback
````

### Code with Explanation
````markdown
---
layout: two-cols
---

```python {1|3-5|7-9|all}
def fibonacci(n):
    """Calculate Fibonacci sequence"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# Generate first 10 numbers
for i in range(10):
    print(fibonacci(i))
```

::right::

# Breakdown

<v-clicks>

1. **Base case** - Handle n ≤ 1
2. **Recursive call** - Sum of previous two
3. **Loop** - Generate sequence

</v-clicks>
````

## Image & Media Templates

### Image with Caption
```markdown
---
layout: image-right
image: /architecture-diagram.png
backgroundSize: contain
---

# System Architecture

Our three-tier architecture ensures:

- Scalability
- Maintainability
- Performance
```

### Full-Screen Image
```markdown
---
layout: image
image: /hero-image.jpg
backgroundSize: cover
class: text-white
---

# Inspiring Quote

"Design is not just what it looks like. Design is how it works."

— Steve Jobs
```

### Video Embed
```markdown
---
layout: default
---

# Product Demo

<Youtube id="dQw4w9WgXcQ" width="800" />

Watch how our product streamlines your workflow
```

### Side-by-Side Images
```markdown
---
layout: two-cols
---

![Before](/before.png)

**Before**: Cluttered interface

::right::

![After](/after.png)

**After**: Clean, modern design
```

## Data & Statistics Templates

### Big Number
```markdown
---
layout: fact
---

# 10,000+

Active users worldwide
```

### Statistics Grid
```markdown
---
layout: center
---

# By The Numbers

<div class="grid grid-cols-3 gap-8 text-center">
  <div>
    <div class="text-5xl font-bold text-blue-500">99.9%</div>
    <div class="text-xl mt-2">Uptime</div>
  </div>
  <div>
    <div class="text-5xl font-bold text-green-500">< 100ms</div>
    <div class="text-xl mt-2">Response Time</div>
  </div>
  <div>
    <div class="text-5xl font-bold text-purple-500">24/7</div>
    <div class="text-xl mt-2">Support</div>
  </div>
</div>
```

### Chart/Diagram
````markdown
---
layout: center
---

# Project Timeline

```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Planning
    Requirements    :a1, 2025-01-01, 30d
    Design         :a2, after a1, 20d
    section Development
    Frontend       :b1, after a2, 45d
    Backend        :b2, after a2, 50d
    section Testing
    QA Testing     :c1, after b1, 20d
```
````

## Interactive Templates

### Navigation Menu
```markdown
---
layout: center
---

# Choose Your Path

<div class="grid grid-cols-2 gap-6 mt-12">
  <Link to="frontend" class="p-8 border-2 border-blue-500 rounded-lg hover:bg-blue-50 transition cursor-pointer">
    <h2 class="text-3xl mb-4">🎨 Frontend</h2>
    <p>React, Vue, Angular</p>
  </Link>

  <Link to="backend" class="p-8 border-2 border-green-500 rounded-lg hover:bg-green-50 transition cursor-pointer">
    <h2 class="text-3xl mb-4">⚙️ Backend</h2>
    <p>Node.js, Python, Go</p>
  </Link>
</div>
```

### Interactive Demo
```markdown
---
layout: center
---

# Try It Yourself

<div class="max-w-md mx-auto">
  <Counter :count="10" />
</div>

<!-- Requires custom Counter component in /components -->
```

### Table of Contents
```markdown
---
layout: center
---

# Agenda

<Toc minDepth="1" maxDepth="1" />
```

## Diagram Templates

### Flowchart
````markdown
---
layout: center
---

# Decision Flow

```mermaid {theme: 'neutral', scale: 0.8}
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Don't touch it]
    B -->|No| D[Did you break it?]
    D -->|Yes| E[Fix it]
    D -->|No| F[Blame someone else]
    E --> B
    C --> G[End]
    F --> G
```
````

### Sequence Diagram
````markdown
---
layout: default
---

# API Flow

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: User created
    API-->>Client: 201 Created
```
````

### Mind Map
````markdown
---
layout: center
---

# Project Structure

```mermaid
mindmap
  root((Project))
    Frontend
      Components
      Pages
      Styles
    Backend
      API
      Database
      Auth
    DevOps
      CI/CD
      Monitoring
      Deployment
```
````

## Quote & Statement Templates

### Quotation
```markdown
---
layout: quote
---

"The only way to do great work is to love what you do."

— Steve Jobs
```

### Bold Statement
```markdown
---
layout: statement
---

# We're changing the future of development
```

### Call to Action
```markdown
---
layout: center
class: text-center
---

# Ready to Get Started?

<div class="mt-12">
  <a href="https://example.com" class="btn-primary text-2xl px-8 py-4 rounded-lg">
    Try It Free
  </a>
</div>

No credit card required · 14-day trial
```

## Closing Slide Templates

### Thank You
```markdown
---
layout: end
class: text-center
---

# Thank You!

## Questions?

Contact: [email protected]

Twitter: @yourhandle
```

### Next Steps
```markdown
---
layout: default
---

# Next Steps

<v-clicks>

1. **Download** the starter kit
2. **Join** our community Slack
3. **Follow** the tutorial
4. **Build** your first project

</v-clicks>

---

🔗 Links: https://example.com/get-started
```

### Contact Info
```markdown
---
layout: center
class: text-center
---

# Let's Connect

<div class="grid grid-cols-3 gap-8 mt-12 text-xl">
  <div>
    <div class="i-mdi:email text-4xl mb-2" />
    <div>[email protected]</div>
  </div>
  <div>
    <div class="i-mdi:twitter text-4xl mb-2" />
    <div>@yourhandle</div>
  </div>
  <div>
    <div class="i-mdi:github text-4xl mb-2" />
    <div>github.com/you</div>
  </div>
</div>
```

## Advanced Pattern Templates

### Progressive Disclosure
```markdown
---
layout: default
---

# Implementation Steps

<v-clicks depth="2">

1. **Setup**
   - Install dependencies
   - Configure environment
2. **Development**
   - Write code
   - Add tests
3. **Deployment**
   - Build production
   - Deploy to server

</v-clicks>
```

### Animated Entrance
```markdown
---
layout: center
---

<div
  v-motion
  :initial="{ x: -80, opacity: 0 }"
  :enter="{ x: 0, opacity: 1, transition: { duration: 800 } }"
>

# Welcome

## Let's build something amazing

</div>
```

### Split Content with Animation
```markdown
---
layout: two-cols
---

<div v-click>

# Challenge

Current solutions are:
- Too complex
- Too expensive
- Too slow

</div>

::right::

<div v-after>

# Our Answer

We provide:
- Simplicity
- Affordability
- Speed

</div>
```

## Usage Notes

1. **Replace placeholders**: Update titles, content, paths, URLs
2. **Adjust styling**: Modify classes, colours, sizes as needed
3. **Add presenter notes**: Include `<!-- notes -->` at slide end
4. **Customize layouts**: Change layout type if needed
5. **Test thoroughly**: Preview all slides before presenting

```

### assets/example-configurations.md

```markdown
# Example Slidev Configurations

Complete example configuration files for common use cases.

## Basic Presentation

### Minimal `slides.md`
```markdown
---
theme: default
title: My Presentation
---

# Welcome

This is a minimal Slidev presentation

---

# Slide 2

Content here

---
layout: end
---

# Thank You
```

## Professional Business Presentation

### `slides.md` Headmatter
```yaml
---
theme: seriph
title: Q4 Business Review
author: Jane Smith
info: |
  ## Q4 2024 Business Review
  Quarterly performance and strategic initiatives

colorSchema: light
class: text-center
mdc: true
transition: slide-left
download: true
exportFilename: q4-business-review

aspectRatio: 16/9
canvasWidth: 980

fonts:
  sans: Inter
  serif: Lora
  weights: '300,400,600,700'
  provider: google

drawings:
  enabled: true
  persist: false
  presenterOnly: true

themeConfig:
  primary: '#1E40AF'
  secondary: '#059669'
---
```

## Technical/Code-Heavy Presentation

### `slides.md` Headmatter
```yaml
---
theme: default
title: Modern JavaScript Patterns
author: Alex Developer
keywords: javascript,typescript,patterns,best-practices

colorSchema: dark
mdc: true
monaco: dev
lineNumbers: true
twoslash: true
highlighter: shiki
transition: slide-left

aspectRatio: 16/9
canvasWidth: 1200

fonts:
  sans: Inter
  mono: JetBrains Mono
  weights: '300,400,600,700'
  provider: google

drawings:
  enabled: false

export:
  format: pdf
  dark: true
  withClicks: true
---
```

### `setup/shiki.ts`
```typescript
import { defineShikiSetup } from '@slidev/types'

export default defineShikiSetup(() => {
  return {
    themes: {
      dark: 'nord',
      light: 'github-light',
    },
    transformers: [],
  }
})
```

### `setup/monaco.ts`
```typescript
import { defineMonacoSetup } from '@slidev/types'

export default defineMonacoSetup(() => {
  return {
    editorOptions: {
      wordWrap: 'on',
      fontSize: 16,
      lineNumbers: 'on',
      minimap: { enabled: false },
      theme: 'vs-dark',
      tabSize: 2,
      fontFamily: 'JetBrains Mono, monospace',
    }
  }
})
```

### `uno.config.ts`
```typescript
import { defineConfig } from 'unocss'
import { presetAttributify, presetUno, presetWebFonts } from 'unocss'

export default defineConfig({
  presets: [
    presetUno(),
    presetAttributify(),
    presetWebFonts({
      fonts: {
        mono: 'JetBrains Mono',
      },
    }),
  ],
  shortcuts: {
    'code-block': 'bg-gray-900 text-gray-100 p-4 rounded',
  },
  safelist: [
    'i-carbon:logo-github',
    'i-carbon:logo-typescript',
  ],
})
```

## Conference/Workshop Presentation

### `slides.md` Headmatter
```yaml
---
theme: seriph
title: Building Scalable Web Apps
info: |
  ## Workshop: Building Scalable Web Apps
  TechConf 2025 - Full-Day Workshop
author: Jamie Technical
keywords: workshop,web,scalability,architecture

colorSchema: auto
background: /conference-bg.jpg
class: text-center

mdc: true
monaco: dev
lineNumbers: true
transition: view-transition
download: true
record: dev
presenter: true

aspectRatio: 16/9
canvasWidth: 980

fonts:
  sans: Roboto
  mono: Fira Code
  weights: '300,400,600,700,900'
  provider: google

drawings:
  enabled: true
  persist: true
  presenterOnly: false
  syncAll: true

export:
  format: pdf
  timeout: 60000
  dark: false
  withClicks: false
  withToc: true

exportFilename: scalable-web-apps-workshop

themeConfig:
  primary: '#6366F1'
  secondary: '#EC4899'

defaults:
  layout: default
  transition: view-transition

htmlAttrs:
  lang: en
  dir: ltr

seoMeta:
  ogTitle: Building Scalable Web Apps Workshop
  ogDescription: Learn modern patterns for building scalable web applications
  ogImage: https://example.com/workshop-cover.jpg
  twitterCard: summary_large_image
---
```

### `setup/shortcuts.ts`
```typescript
import { defineShortcutsSetup, NavOperations } from '@slidev/types'

export default defineShortcutsSetup((nav: NavOperations) => {
  return [
    {
      key: 'ctrl+shift+enter',
      fn: () => nav.next(),
      autoRepeat: true,
    },
    {
      key: 'ctrl+shift+backspace',
      fn: () => nav.prev(),
      autoRepeat: true,
    },
  ]
})
```

## Educational/Tutorial Presentation

### `slides.md` Headmatter
```yaml
---
theme: default
title: Introduction to Vue.js
info: |
  ## Introduction to Vue.js
  A beginner-friendly guide to modern web development
author: Chris Educator

colorSchema: light
class: text-left
mdc: true
monaco: dev
lineNumbers: true
transition: slide-left

aspectRatio: 16/9
canvasWidth: 980

fonts:
  sans: Open Sans
  mono: Source Code Pro
  weights: '400,600,700'
  provider: google

drawings:
  enabled: true
  persist: true

export:
  format: pdf
  withClicks: false

themeConfig:
  primary: '#42B883'
  secondary: '#35495E'
---
```

### `setup/mermaid.ts`
```typescript
import { defineMermaidSetup } from '@slidev/types'

export default defineMermaidSetup(() => {
  return {
    theme: 'base',
    themeVariables: {
      primaryColor: '#42B883',
      primaryTextColor: '#fff',
      primaryBorderColor: '#35495E',
      lineColor: '#35495E',
      secondaryColor: '#35495E',
      tertiaryColor: '#fff',
    }
  }
})
```

## Minimalist/Design-Focused Presentation

### `slides.md` Headmatter
```yaml
---
theme: apple-basic
title: Product Design Principles
author: Designer Name

colorSchema: light
class: text-center
transition: fade
download: false

aspectRatio: 16/9
canvasWidth: 980

fonts:
  sans: SF Pro Display
  serif: New York
  weights: '300,400,500,600'
  provider: none
  local: SF Pro Display,New York

drawings:
  enabled: false

themeConfig:
  primary: '#000000'
  secondary: '#666666'

defaults:
  layout: center
  transition: fade
---
```

### `styles/index.css`
```css
/* Custom global styles */
:root {
  --color-primary: #000000;
  --color-secondary: #666666;
  --spacing-unit: 1rem;
}

.slidev-layout {
  font-size: 1.5rem;
  line-height: 1.6;
}

h1 {
  font-weight: 600;
  font-size: 4rem;
  letter-spacing: -0.02em;
  margin-bottom: 2rem;
}

h2 {
  font-weight: 500;
  font-size: 2.5rem;
  letter-spacing: -0.01em;
}

p {
  font-weight: 400;
  max-width: 40rem;
  margin-inline: auto;
}
```

## Multi-File Presentation

### `slides.md` (Main file)
```markdown
---
theme: seriph
title: Complete Product Overview
---

# Welcome

Product Overview Presentation

---
src: ./pages/introduction.md
---

---
src: ./pages/features.md
---

---
src: ./pages/demo.md
---

---
src: ./pages/pricing.md
---

---
layout: end
---

# Thank You
```

### `pages/introduction.md`
```markdown
---
layout: section
---

# Introduction

---

# About Our Company

Founded in 2020...

---

# Mission Statement

To revolutionize...
```

### `pages/features.md`
```markdown
---
layout: section
---

# Features

---
layout: two-cols
---

# Core Features

- Feature 1
- Feature 2

::right::

# Advanced Features

- Advanced 1
- Advanced 2
```

## Complete Project Example

### Directory Structure
```
my-presentation/
├── slides.md
├── package.json
├── slidev.config.ts
├── uno.config.ts
├── vite.config.ts
├── components/
│   ├── Logo.vue
│   └── StatsCard.vue
├── layouts/
│   └── custom.vue
├── pages/
│   ├── intro.md
│   └── demo.md
├── public/
│   ├── images/
│   ├── videos/
│   └── fonts/
├── setup/
│   ├── main.ts
│   ├── shiki.ts
│   ├── monaco.ts
│   └── shortcuts.ts
└── styles/
    └── index.css
```

### `package.json`
```json
{
  "name": "my-presentation",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "slidev --open",
    "build": "slidev build",
    "export": "slidev export",
    "export:pptx": "slidev export --format pptx",
    "format": "slidev format"
  },
  "dependencies": {
    "@slidev/cli": "^0.52.6",
    "@slidev/theme-seriph": "^0.27.1"
  },
  "devDependencies": {
    "playwright-chromium": "^1.40.0",
    "unocss": "^0.58.0",
    "vite": "^5.0.0"
  }
}
```

### `slidev.config.ts`
```typescript
import { defineConfig } from '@slidev/cli'

export default defineConfig({
  theme: 'seriph',
  highlighter: 'shiki',
  lineNumbers: true,
  monaco: 'dev',
  routerMode: 'history',
  aspectRatio: 16 / 9,
  canvasWidth: 980,

  fonts: {
    sans: 'Inter',
    mono: 'JetBrains Mono',
    weights: '300,400,600,700',
    provider: 'google',
  },

  drawings: {
    enabled: true,
    persist: true,
    syncAll: true,
  },

  exportFilename: 'presentation',
  download: true,
  mdc: true,
})
```

### `vite.config.ts`
```typescript
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 3030,
    open: true,
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
  },
})
```

### `setup/main.ts`
```typescript
import { defineAppSetup } from '@slidev/types'
import Logo from '../components/Logo.vue'
import StatsCard from '../components/StatsCard.vue'

export default defineAppSetup(({ app }) => {
  // Register global components
  app.component('Logo', Logo)
  app.component('StatsCard', StatsCard)

  // Global properties
  app.config.globalProperties.$formatNumber = (n: number) => {
    return new Intl.NumberFormat('en-US').format(n)
  }
})
```

## Quick Start Templates

### 3-Slide Minimum
```markdown
---
theme: default
title: Quick Demo
---

# Title

Introduction

---

# Content

Main points

---
layout: end
---

# End
```

### 10-Slide Standard
```markdown
---
theme: seriph
title: Standard Presentation
---

# Cover

---
layout: section
---

# Section 1

---

# Slide 3

---

# Slide 4

---
layout: section
---

# Section 2

---

# Slide 6

---

# Slide 7

---
layout: two-cols
---

# Comparison

::right::

# Results

---
layout: section
---

# Conclusion

---
layout: end
---

# Thank You
```

## Configuration Best Practices

### 1. Start Simple
```yaml
---
theme: default
title: My Talk
---
```

### 2. Add Features as Needed
```yaml
---
theme: default
title: My Talk
mdc: true
lineNumbers: true
---
```

### 3. Optimize for Use Case
```yaml
---
# Code presentations
monaco: dev
lineNumbers: true
twoslash: true

# OR design presentations
transition: fade
drawings: false
```

### 4. Test Before Presenting
```bash
# Test locally
slidev

# Test build
slidev build
npx serve dist

# Test export
slidev export --range 1-5
```

```

### references/layouts-reference.md

```markdown
# Slidev Layouts Reference

This reference documents all 17 built-in Slidev layouts with usage examples and when to use each.

## Layout Overview

Layouts control the structure and styling of individual slides. Specify a layout using frontmatter:

```yaml
---
layout: layout-name
---
```

## Built-in Layouts

### 1. cover
**Purpose**: Title slide for presentation opening
**Best for**: First slide, major section starts

```markdown
---
layout: cover
background: /cover-image.jpg
class: text-center
---

# Presentation Title

## Subtitle

Author Name · Date/Event
```

**Common options**:
- `background`: Image URL or gradient
- `class`: CSS classes (text-center, text-left)

---

### 2. default
**Purpose**: Standard content layout
**Best for**: General content, bullet points, paragraphs

```markdown
---
layout: default
---

# Slide Title

- Bullet point 1
- Bullet point 2
- Bullet point 3

Regular paragraph text works here too.
```

---

### 3. center
**Purpose**: Vertically and horizontally centred content
**Best for**: Short quotes, key statements, simple diagrams

```markdown
---
layout: center
---

# Centred Title

All content is centred on the slide
```

---

### 4. section
**Purpose**: Section divider
**Best for**: Marking transitions between presentation parts

```markdown
---
layout: section
background: linear-gradient(to right, #667eea, #764ba2)
class: text-white
---

# Part 2: Implementation
```

---

### 5. statement
**Purpose**: Bold statement or key message
**Best for**: Emphasis, key takeaways, memorable quotes

```markdown
---
layout: statement
---

# A Bold Statement

Supporting text if needed
```

---

### 6. fact
**Purpose**: Highlight statistics or data
**Best for**: Numbers, metrics, important facts

```markdown
---
layout: fact
---

# 95%

Success rate achieved

```

---

### 7. quote
**Purpose**: Display quotations
**Best for**: Testimonials, famous quotes, citations

```markdown
---
layout: quote
---

"Design is not just what it looks like and feels like. Design is how it works."

— Steve Jobs
```

---

### 8. end
**Purpose**: Final slide
**Best for**: Thank you slide, Q&A, contact information

```markdown
---
layout: end
---

# Thank You

Questions?

[email protected]
```

---

### 9. two-cols
**Purpose**: Two-column layout
**Best for**: Comparisons, before/after, contrasting concepts

```markdown
---
layout: two-cols
---

# Left Column

Content on the left side

::right::

# Right Column

Content on the right side
```

**Named slots**:
- Default: Left column
- `::right::`: Right column

---

### 10. two-cols-header
**Purpose**: Header spanning both columns, then split content
**Best for**: Shared title with different details below

```markdown
---
layout: two-cols-header
---

# Full-Width Header

Spans both columns

::left::

Left content here

::right::

Right content here
```

**Named slots**:
- Default: Header (full width)
- `::left::`: Left column
- `::right::`: Right column

---

### 11. image-left
**Purpose**: Image on left, content on right
**Best for**: Diagrams with explanations, screenshots with text

```markdown
---
layout: image-left
image: /diagram.png
backgroundSize: contain
---

# Explanation Title

- Point 1
- Point 2
- Point 3
```

**Options**:
- `image`: Path to image (required)
- `backgroundSize`: cover | contain | custom (default: cover)
- `class`: Custom classes for content area

---

### 12. image-right
**Purpose**: Image on right, content on left
**Best for**: Diagrams with explanations, screenshots with text

```markdown
---
layout: image-right
image: /architecture.png
backgroundSize: contain
class: my-content
---

# System Architecture

Content on the left explains the diagram on the right
```

**Options**: Same as image-left

---

### 13. image
**Purpose**: Full-screen image background
**Best for**: Photo slides, visual breaks, background images

```markdown
---
layout: image
image: /background.jpg
backgroundSize: cover
---

# Title Over Image

Optional content overlaid on image
```

---

### 14. iframe
**Purpose**: Embed full-screen web page
**Best for**: Live demos, web documentation, interactive content

```markdown
---
layout: iframe
url: https://github.com/slidevjs/slidev
---
```

**Note**: No additional content displays with this layout

---

### 15. iframe-left
**Purpose**: Web page on left, content on right
**Best for**: Explaining a website, showing live examples

```markdown
---
layout: iframe-left
url: https://example.com
---

# About This Site

- Feature 1
- Feature 2
- Feature 3
```

---

### 16. iframe-right
**Purpose**: Web page on right, content on left
**Best for**: Explaining a website, showing live examples

```markdown
---
layout: iframe-right
url: https://sli.dev
---

# Slidev Official Site

Content on left, live site on right
```

---

### 17. none
**Purpose**: Blank layout for full custom control
**Best for**: Completely custom slides, special designs

```markdown
---
layout: none
---

<div class="absolute inset-0 flex items-center justify-center">
  <h1>Completely Custom</h1>
</div>
```

## Custom Layouts

Create custom layouts in `./layouts/custom-name.vue`:

```vue
<template>
  <div class="slidev-layout my-custom-layout">
    <div class="header">
      <slot name="header" />
    </div>
    <div class="content">
      <slot />
    </div>
    <div class="footer">
      <slot name="footer" />
    </div>
  </div>
</template>

<style scoped>
.my-custom-layout {
  padding: 2rem;
}
</style>
```

Usage:
```markdown
---
layout: custom-name
---

::header::
Header content

Main content

::footer::
Footer content
```

## Layout Selection Guide

| Use Case | Recommended Layout |
|----------|-------------------|
| Title slide | cover |
| Section divider | section |
| Standard content | default |
| Short quote | center |
| Big number/stat | fact |
| Long quote | quote |
| Comparison | two-cols |
| Image + text | image-left/right |
| Full image | image |
| Live website | iframe/iframe-left/right |
| Final slide | end |
| Custom design | none |

## Common Patterns

### Progressive Comparison
```markdown
---
layout: two-cols
---

# Before

```js
var x = 1
```

::right::

# After

```js
const x = 1
```
```

### Image with Explanation
```markdown
---
layout: image-right
image: /diagram.png
backgroundSize: contain
---

# Architecture

<v-clicks>

- Layer 1: Presentation
- Layer 2: Business Logic
- Layer 3: Data Access

</v-clicks>
```

### Live Demo with Notes
```markdown
---
layout: iframe-left
url: http://localhost:3000
---

# Try It Out

1. Click the button
2. Enter your name
3. See the result

<!-- Presenter note: Make sure dev server is running -->
```

```

### references/components-reference.md

```markdown
# Slidev Components Reference

Complete reference for all built-in Slidev components and custom component patterns.

## Built-in Components

### Click Animation Components

#### `<v-click>`
Show elements on click.

```markdown
<v-click>Appears on first click</v-click>
<v-click>Appears on second click</v-click>

<!-- Absolute positioning -->
<v-click at="3">Appears on third click</v-click>

<!-- Relative positioning -->
<v-click at="+2">Skip one click</v-click>

<!-- Hide after click -->
<v-click hide>Hidden after click</v-click>
<v-click hide at="[2, 4]">Visible only clicks 2-3</v-click>
```

#### `v-click` Directive
Alternative syntax using directive:

```markdown
<div v-click>Directive syntax</div>
<div v-click="3">At click 3</div>
<div v-click.hide>Hide on click</div>
```

#### `<v-clicks>`
Batch click animations for lists:

```markdown
<v-clicks>

- Item 1
- Item 2
- Item 3

</v-clicks>

<!-- Nested lists with depth -->
<v-clicks depth="2">

- Parent 1
  - Child 1.1
  - Child 1.2
- Parent 2

</v-clicks>

<!-- Every N items -->
<v-clicks every="2">

- Items 1-2 (click 1)
- Items 3-4 (click 2)

</v-clicks>
```

#### `<v-after>`
Appears with previous click:

```markdown
<div v-click>First</div>
<div v-after>Also appears on first click</div>
```

#### `<v-switch>`
Switch content on specific clicks:

```markdown
<v-switch>
  <template #1>Content for click 1</template>
  <template #2>Content for click 2</template>
  <template #5-7>Content for clicks 5-6</template>
</v-switch>
```

### Interactive Components

#### `<v-drag>`
Draggable containers:

```markdown
<!-- Position: left,top,width,height,rotate -->
<v-drag pos="100,200,300,50,0">
  Drag me around!
</v-drag>

<!-- Bind to frontmatter -->
---
dragPos:
  myElement: 10,20,200,100,0
---

<v-drag pos="myElement">
  Draggable element
</v-drag>
```

#### `<v-drag-arrow>`
Draggable arrows:

```markdown
<v-drag-arrow />

<!-- Two-way arrow -->
<v-drag-arrow two-way />

<!-- With position -->
<v-drag-arrow pos="67,452,253,46" two-way op70 />
```

### Media Components

#### `<Tweet>`
Embed Twitter posts:

```markdown
<Tweet id="1390115482657726468" />

<!-- With scale -->
<Tweet id="1390115482657726468" scale="0.8" />

<!-- Options -->
<Tweet
  id="1390115482657726468"
  scale="0.65"
  conversation="none"
  cards="hidden"
/>
```

**Props**:
- `id` (required): Tweet ID
- `scale`: Size scaling (default: 1)
- `conversation`: Show conversation thread
- `cards`: Show/hide Twitter cards

#### `<Youtube>`
Embed YouTube videos:

```markdown
<Youtube id="luoMHjh-XcQ" />

<!-- With dimensions -->
<Youtube id="luoMHjh-XcQ" width="800" height="450" />

<!-- Start at specific time (60 seconds) -->
<Youtube id="luoMHjh-XcQ?start=60" />
```

**Props**:
- `id` (required): Video ID (optionally with ?start=N)
- `width`: Video width (default: 560)
- `height`: Video height (default: 315)

#### `<SlidevVideo>`
Video player with controls:

```markdown
<SlidevVideo autoplay controls>
  <source src="/demo.mp4" type="video/mp4" />
  <source src="/demo.webm" type="video/webm" />
</SlidevVideo>

<!-- With poster -->
<SlidevVideo controls poster="/thumbnail.jpg">
  <source src="/video.mp4" type="video/mp4" />
</SlidevVideo>
```

**Attributes**:
- `autoplay`: Auto-play video
- `controls`: Show controls
- `loop`: Loop video
- `muted`: Mute audio
- `poster`: Poster image URL

### Utility Components

#### `<Arrow>`
Draw arrows between elements:

```markdown
<!-- Basic arrow -->
<Arrow x1="10" y1="20" x2="100" y2="200" />

<!-- Styled arrow -->
<Arrow
  x1="10"
  y1="20"
  x2="100"
  y2="200"
  color="#953"
  width="2"
/>

<!-- Using v-bind -->
<Arrow v-bind="{ x1:10, y1:10, x2:200, y2:200 }" />
```

**Props**:
- `x1`, `y1`: Start coordinates
- `x2`, `y2`: End coordinates
- `width`: Line width (default: 2)
- `color`: Arrow colour (default: currentColor)

#### `<Link>`
Navigate to slides:

```markdown
<!-- By slide number -->
<Link to="42">Go to slide 42</Link>

<!-- By route alias -->
<Link to="solutions" title="Jump to solutions" />

<!-- With custom styling -->
<Link to="10" class="btn">Next Section</Link>
```

**Props**:
- `to` (required): Slide number or route alias
- `title`: Link text (optional)

#### `<Toc>`
Table of contents:

```markdown
<!-- Basic TOC -->
<Toc />

<!-- With depth limits -->
<Toc minDepth="1" maxDepth="2" />

<!-- Only level 1 headings -->
<Toc minDepth="1" maxDepth="1" />
```

**Props**:
- `minDepth`: Minimum heading level (default: 1)
- `maxDepth`: Maximum heading level (default: Infinity)

**Note**: Slides with `hideInToc: true` in frontmatter are excluded.

#### `<Transform>`
Scale content:

```markdown
<Transform :scale="0.8">
  <YourContent />
</Transform>

<!-- With origin -->
<Transform :scale="0.5" origin="top left">
  <YourContent />
</Transform>
```

**Props**:
- `scale`: Scale factor (required)
- `origin`: Transform origin (default: "center")

#### `<LightOrDark>`
Conditional rendering based on theme:

```markdown
<LightOrDark>
  <template #dark>
    <img src="/dark-logo.png" />
  </template>
  <template #light>
    <img src="/light-logo.png" />
  </template>
</LightOrDark>

<!-- With scoped slot props -->
<LightOrDark width="100" alt="Logo">
  <template #dark="props">
    <img src="/dark.png" v-bind="props" />
  </template>
  <template #light="props">
    <img src="/light.png" v-bind="props" />
  </template>
</LightOrDark>
```

#### `<RenderWhen>`
Conditional rendering by context:

```markdown
<!-- Only in presenter view -->
<RenderWhen context="presenter">
  This text only appears in presenter mode
</RenderWhen>

<!-- Multiple contexts -->
<RenderWhen context="['presenter', 'main']">
  Appears in presenter and main views
</RenderWhen>
```

**Props**:
- `context`: Context name or array of contexts

#### `<AutoFitText>`
Auto-resize text to fit:

```markdown
<AutoFitText :max="200" :min="100" modelValue="Some text" />
```

**Props**:
- `modelValue`: Text content (required)
- `max`: Maximum font size
- `min`: Minimum font size

### Motion Animations

#### `v-motion` Directive
From `@vueuse/motion`:

```markdown
<div
  v-motion
  :initial="{ x: -80, opacity: 0 }"
  :enter="{ x: 0, opacity: 1 }"
  :leave="{ x: 80, opacity: 0 }"
>
  Animated element
</div>

<!-- Click-triggered animations -->
<div
  v-motion
  :initial="{ x: -80 }"
  :enter="{ x: 0 }"
  :click-1="{ x: 0, y: 30 }"
  :click-2="{ y: 60 }"
  :click-3="{ scale: 1.2 }"
>
  Interactive animation
</div>

<!-- With transition config -->
<script setup>
const config = {
  x: 0,
  y: 0,
  transition: {
    type: 'spring',
    stiffness: 20,
    damping: 10
  }
}
</script>

<div v-motion :enter="config">
  Spring animation
</div>
```

**Animation properties**:
- `x`, `y`: Translation
- `scale`: Scaling
- `rotate`: Rotation (degrees)
- `opacity`: Opacity (0-1)
- `transition`: Transition configuration

## Custom Components

### Creating Custom Components

**File**: `components/MyButton.vue`

```vue
<script setup lang="ts">
import { ref } from 'vue'

const props = defineProps({
  variant: {
    type: String,
    default: 'primary',
    validator: (v: string) => ['primary', 'secondary'].includes(v)
  }
})

const count = ref(0)
</script>

<template>
  <button
    class="btn"
    :class="`btn-${variant}`"
    @click="count++"
  >
    <slot /> ({{ count }})
  </button>
</template>

<style scoped>
.btn {
  padding: 0.5rem 1rem;
  border-radius: 0.25rem;
  font-weight: 600;
  cursor: pointer;
  transition: all 0.2s;
}

.btn-primary {
  background: #5b21b6;
  color: white;
}

.btn-primary:hover {
  background: #6d28d9;
}

.btn-secondary {
  background: #0891b2;
  color: white;
}
</style>
```

**Usage**:
```markdown
<MyButton>Click Me</MyButton>
<MyButton variant="secondary">Secondary Button</MyButton>
```

**Note**: Components in `/components` are auto-imported.

### Custom Component Patterns

#### Interactive Counter
```vue
<script setup lang="ts">
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++
const decrement = () => count.value--
</script>

<template>
  <div class="counter">
    <button @click="decrement">-</button>
    <span>{{ count }}</span>
    <button @click="increment">+</button>
  </div>
</template>
```

#### Animated Card
```vue
<script setup lang="ts">
defineProps<{
  title: string
  icon?: string
}>()
</script>

<template>
  <div class="card" v-motion :initial="{ opacity: 0, y: 20 }" :enter="{ opacity: 1, y: 0 }">
    <div v-if="icon" class="icon" :class="icon" />
    <h3>{{ title }}</h3>
    <div class="content">
      <slot />
    </div>
  </div>
</template>

<style scoped>
.card {
  padding: 1.5rem;
  border-radius: 0.5rem;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
  background: white;
}
</style>
```

#### Code Demo Component
```vue
<script setup lang="ts">
import { ref } from 'vue'

const props = defineProps<{
  code: string
  language?: string
}>()

const output = ref('')

const runCode = () => {
  try {
    output.value = eval(props.code)
  } catch (e) {
    output.value = `Error: ${e.message}`
  }
}
</script>

<template>
  <div class="code-demo">
    <div class="code-block">
      <slot />
    </div>
    <button @click="runCode">Run Code</button>
    <div v-if="output" class="output">
      {{ output }}
    </div>
  </div>
</template>
```

## Component Best Practices

### Performance
1. **Use `v-if` for conditional components**: More efficient than `v-show` for rarely-toggled content
2. **Minimize reactive dependencies**: Only make necessary data reactive
3. **Lazy load heavy components**: Import components dynamically when needed

### Accessibility
1. **Semantic HTML**: Use appropriate HTML elements
2. **Keyboard navigation**: Ensure interactive elements are keyboard-accessible
3. **ARIA labels**: Add aria-label for icon-only buttons
4. **Focus management**: Handle focus for modal-like components

### Styling
1. **Scoped styles**: Use `<style scoped>` to prevent style leakage
2. **UnoCSS classes**: Leverage utility classes for common styling
3. **CSS variables**: Use theme variables for consistency
4. **Responsive design**: Consider different screen sizes

### Composition
1. **Single responsibility**: Each component should do one thing well
2. **Props validation**: Define prop types and validators
3. **Emit events**: Use emits for parent communication
4. **Slots**: Provide slots for flexible content injection

## Component Selection Guide

| Use Case | Component |
|----------|-----------|
| Click animations | `<v-click>` or `<v-clicks>` |
| List animations | `<v-clicks>` |
| Content switching | `<v-switch>` |
| Draggable elements | `<v-drag>` |
| Arrows | `<Arrow>` or `<v-drag-arrow>` |
| Navigation | `<Link>` |
| TOC | `<Toc>` |
| Scaling | `<Transform>` |
| Theme switching | `<LightOrDark>` |
| Twitter posts | `<Tweet>` |
| YouTube videos | `<Youtube>` |
| Local videos | `<SlidevVideo>` |
| Motion | `v-motion` directive |
| Context-specific | `<RenderWhen>` |

```

### references/configuration-reference.md

```markdown
# Slidev Configuration Reference

Complete reference for all Slidev configuration options.

## Configuration Methods

Slidev can be configured through:
1. **Headmatter**: First slide's YAML frontmatter (most common)
2. **slidev.config.ts**: TypeScript configuration file
3. **Per-slide frontmatter**: Individual slide configuration

## Headmatter (Global Configuration)

The first slide's frontmatter configures the entire presentation.

### Complete Headmatter Example

```yaml
---
# Theme
theme: seriph
colorSchema: auto

# Metadata
title: My Presentation
info: |
  ## Detailed Description
  Multi-line markdown supported
author: Jane Developer
keywords: vue,typescript,presentations

# Appearance
background: /cover.jpg
class: text-center

# Features
mdc: true
monaco: dev
lineNumbers: true
twoslash: true
download: true
presenter: true
record: dev

# Transitions
transition: slide-left
drawings:
  enabled: true
  persist: true
  presenterOnly: false
  syncAll: true

# Layout
aspectRatio: 16/9
canvasWidth: 980
routerMode: history

# Fonts
fonts:
  sans: Inter
  serif: Lora
  mono: JetBrains Mono
  weights: '300,400,600,700'
  italic: true
  provider: google

# Export
exportFilename: my-presentation
export:
  format: pdf
  timeout: 30000
  dark: false
  withClicks: false
  withToc: true

# Highlighting
highlighter: shiki
contextMenu: true
selectable: true
wakeLock: true

# Theme Configuration
themeConfig:
  primary: '#5b21b6'
  secondary: '#0891b2'

# Defaults
defaults:
  layout: default
  transition: fade

# SEO
htmlAttrs:
  lang: en
  dir: ltr
seoMeta:
  ogTitle: My Presentation
  ogDescription: Description for social sharing
  ogImage: https://example.com/cover.jpg
  twitterCard: summary_large_image
---
```

### Headmatter Options Reference

#### Theme & Appearance

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `theme` | string | `'default'` | Theme name or path |
| `colorSchema` | `'auto'` \| `'light'` \| `'dark'` | `'auto'` | Colour scheme |
| `background` | string | - | Global background (URL or gradient) |
| `class` | string | - | Global CSS classes |

#### Metadata

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | string | `'Slidev'` | Presentation title |
| `titleTemplate` | string | `'%s - Slidev'` | Browser title template |
| `info` | string | - | Presentation description (markdown) |
| `author` | string | - | Author name (for exports) |
| `keywords` | string | - | Comma-separated keywords |

#### Features

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mdc` | boolean | `false` | Enable MDC syntax |
| `monaco` | `boolean` \| `'dev'` \| `'build'` | `false` | Monaco editor |
| `lineNumbers` | boolean | `false` | Show line numbers in code blocks |
| `twoslash` | boolean | `false` | Enable TwoSlash for TypeScript |
| `download` | boolean | `false` | Show download button |
| `presenter` | boolean | `true` | Enable presenter mode |
| `record` | `boolean` \| `'dev'` \| `'build'` | `false` | Enable recording |
| `contextMenu` | boolean | `true` | Enable right-click menu |
| `selectable` | boolean | `true` | Allow text selection |
| `wakeLock` | boolean | `true` | Prevent screen sleep |

#### Transitions & Animations

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `transition` | string \| object | `'fade'` | Global slide transition |
| `drawings.enabled` | boolean | `true` | Enable drawing |
| `drawings.persist` | boolean | `false` | Save drawings |
| `drawings.presenterOnly` | boolean | `false` | Drawing in presenter only |
| `drawings.syncAll` | boolean | `true` | Sync drawings across devices |

#### Layout

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `aspectRatio` | number | `16/9` | Slide aspect ratio |
| `canvasWidth` | number | `980` | Canvas width (px) |
| `routerMode` | `'history'` \| `'hash'` | `'history'` | Router mode |

#### Fonts

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `fonts.sans` | string | - | Sans-serif font |
| `fonts.serif` | string | - | Serif font |
| `fonts.mono` | string | - | Monospace font |
| `fonts.weights` | string | `'200,400,600'` | Font weights |
| `fonts.italic` | boolean | `true` | Include italic variants |
| `fonts.provider` | `'google'` \| `'none'` | `'google'` | Font provider |
| `fonts.local` | string | - | Local font names |

#### Export

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `exportFilename` | string | `'slides-export'` | Export filename |
| `export.format` | `'pdf'` \| `'pptx'` \| `'png'` \| `'md'` | `'pdf'` | Export format |
| `export.timeout` | number | `30000` | Export timeout (ms) |
| `export.dark` | boolean | `false` | Export in dark mode |
| `export.withClicks` | boolean | `false` | Include click animations |
| `export.withToc` | boolean | `false` | Include PDF outline |

#### Code Highlighting

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `highlighter` | `'shiki'` | `'shiki'` | Code highlighter |
| `monacoTypesSource` | `'cdn'` \| `'local'` \| `'ata'` | `'cdn'` | Monaco types source |

#### Theme Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `themeConfig` | object | `{}` | Theme-specific configuration |

**Example**:
```yaml
---
themeConfig:
  primary: '#5b21b6'
  secondary: '#0891b2'
  logoUrl: /logo.png
---
```

#### Defaults

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaults.layout` | string | `'default'` | Default layout |
| `defaults.transition` | string | `'fade'` | Default transition |

## Per-Slide Frontmatter

Configure individual slides with frontmatter after slide separators.

### Per-Slide Options

```yaml
---
# Layout
layout: center

# Appearance
background: /image.jpg
class: text-white

# Behaviour
clicks: 5
clicksStart: 0
preload: true
disabled: false
hide: false
hideInToc: false

# Transition
transition: slide-left
zoom: 0.8

# Navigation
level: 1
title: Custom Title
routeAlias: solutions

# Import
src: ./pages/external.md

# Draggable positions
dragPos:
  element1: 100,200,300,50,0
---
```

### Per-Slide Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `layout` | string | `'default'` or `'cover'` | Slide layout |
| `background` | string | - | Background image or gradient |
| `class` | string | - | CSS classes for slide |
| `clicks` | number | `0` | Number of clicks |
| `clicksStart` | number | `0` | Starting click index |
| `transition` | string | - | Slide transition override |
| `zoom` | number | `1` | Content zoom level |
| `level` | number | `1` | Heading level for TOC |
| `title` | string | - | Slide title override |
| `hideInToc` | boolean | `false` | Hide from table of contents |
| `routeAlias` | string | - | Navigation alias |
| `src` | string | - | Import external slide |
| `preload` | boolean | `true` | Preload slide |
| `disabled` | boolean | `false` | Disable slide |
| `hide` | boolean | `false` | Hide slide completely |
| `dragPos` | object | `{}` | Draggable element positions |

## slidev.config.ts

TypeScript configuration file (optional, alternative to headmatter).

### Complete Example

```typescript
import { defineConfig } from '@slidev/cli'

export default defineConfig({
  // Theme
  theme: 'seriph',

  // Features
  highlighter: 'shiki',
  lineNumbers: true,
  monaco: 'dev',
  mdc: true,

  // Layout
  routerMode: 'history',
  aspectRatio: 16 / 9,
  canvasWidth: 980,

  // Fonts
  fonts: {
    sans: 'Inter',
    serif: 'Lora',
    mono: 'JetBrains Mono',
    weights: '300,400,600',
    provider: 'google',
  },

  // Drawing
  drawings: {
    enabled: true,
    persist: true,
    syncAll: true,
  },

  // Export
  exportFilename: 'presentation',
  download: true,

  // Transitions
  transition: 'slide-left',
})
```

## Setup Files

Advanced configuration through setup files in `./setup/` directory.

### Shiki Configuration

**File**: `setup/shiki.ts`

```typescript
import { defineShikiSetup } from '@slidev/types'

export default defineShikiSetup(() => {
  return {
    themes: {
      dark: 'nord',
      light: 'min-light',
    },
    transformers: [
      // Custom transformers
    ],
  }
})
```

### Monaco Configuration

**File**: `setup/monaco.ts`

```typescript
import { defineMonacoSetup } from '@slidev/types'

export default defineMonacoSetup(() => {
  return {
    editorOptions: {
      wordWrap: 'on',
      fontSize: 14,
      lineNumbers: 'on',
      minimap: { enabled: false },
      theme: 'vs-dark',
    }
  }
})
```

### Mermaid Configuration

**File**: `setup/mermaid.ts`

```typescript
import { defineMermaidSetup } from '@slidev/types'

export default defineMermaidSetup(() => {
  return {
    theme: 'forest',
    themeVariables: {
      primaryColor: '#ff0000',
      primaryTextColor: '#fff',
      primaryBorderColor: '#000',
    }
  }
})
```

### UnoCSS Configuration

**File**: `uno.config.ts`

```typescript
import { defineConfig } from 'unocss'
import { presetAttributify, presetUno } from 'unocss'

export default defineConfig({
  presets: [
    presetUno(),
    presetAttributify(),
  ],
  shortcuts: {
    'btn': 'px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600',
    'card': 'p-6 rounded-lg shadow-lg bg-white dark:bg-gray-800',
  },
  theme: {
    colors: {
      primary: '#5b21b6',
    },
  },
  safelist: [
    'i-carbon:checkmark',
    'i-mdi:github',
  ],
})
```

### App Setup

**File**: `setup/main.ts`

```typescript
import { defineAppSetup } from '@slidev/types'

export default defineAppSetup(({ app, router }) => {
  // Register global components
  app.component('MyComponent', MyComponent)

  // Router guards
  router.beforeEach((to, from) => {
    console.log('Navigating to:', to.path)
  })

  // Global properties
  app.config.globalProperties.$myUtil = () => {
    return 'Utility function'
  }
})
```

### Custom Shortcuts

**File**: `setup/shortcuts.ts`

```typescript
import { defineShortcutsSetup, NavOperations } from '@slidev/types'

export default defineShortcutsSetup((nav: NavOperations) => {
  return [
    {
      key: 'ctrl+shift+enter',
      fn: () => nav.next(),
      autoRepeat: true,
    },
    {
      key: 'ctrl+shift+p',
      fn: () => nav.togglePresenter(),
    },
  ]
})
```

### Preparser/Transformers

**File**: `setup/preparser.ts`

```typescript
import { definePreparserSetup } from '@slidev/types'

export default definePreparserSetup(() => {
  return [
    {
      transformRawLines(lines) {
        for (let i = 0; i < lines.length; i++) {
          // Custom transformations
          if (lines[i] === '@@@')
            lines[i] = '---'
        }
      },
    }
  ]
})
```

## Vite Configuration

**File**: `vite.config.ts`

```typescript
import { defineConfig } from 'vite'

export default defineConfig({
  slidev: {
    vue: {
      /* Vue options */
    },
    markdown: {
      /* markdown-it options */
      markdownItSetup(md) {
        md.use(MyMarkdownPlugin)
      },
    },
  },
  server: {
    port: 3030,
  },
  build: {
    outDir: 'dist',
  },
})
```

## Configuration Priority

When the same option is set in multiple places:

1. Per-slide frontmatter (highest priority)
2. Headmatter
3. slidev.config.ts
4. Setup files
5. Default values (lowest priority)

## Common Configuration Patterns

### Minimal Setup
```yaml
---
theme: default
title: My Presentation
---
```

### Standard Professional
```yaml
---
theme: seriph
title: Technical Workshop
author: Jane Developer
mdc: true
lineNumbers: true
transition: slide-left
fonts:
  sans: Inter
  mono: JetBrains Mono
---
```

### Code-Heavy Presentation
```yaml
---
theme: default
title: Code Deep Dive
monaco: dev
lineNumbers: true
twoslash: true
highlighter: shiki
fonts:
  mono: JetBrains Mono
aspectRatio: 16/9
canvasWidth: 1200
---
```

### Conference Talk
```yaml
---
theme: seriph
title: Modern Web Development
info: |
  ## Conference Talk
  TechConf 2025
author: Jane Developer
download: true
exportFilename: techconf-2025-talk
drawings:
  enabled: true
  persist: false
record: dev
---
```

## Environment Variables

Set via `.env` file or environment:

```bash
# Development
SLIDEV_PORT=3030
SLIDEV_OPEN=true

# Export
SLIDEV_EXPORT_DARK=true
SLIDEV_EXPORT_WITH_CLICKS=false
```

## Configuration Troubleshooting

### Theme not loading
- Check theme name spelling
- Verify theme is installed: `npm list | grep slidev-theme`
- Try absolute path for local themes

### Fonts not appearing
- Verify `provider` is set correctly
- Check internet connection for CDN fonts
- Use local fonts if CDN is blocked

### Monaco not working
- Check `monaco: 'dev'` or `monaco: true` in config
- Verify TypeScript files have proper types
- Set `monacoTypesSource: 'ata'` for auto type acquisition

### Export failing
- Install playwright: `pnpm add -D playwright-chromium`
- Increase timeout: `export.timeout: 60000`
- Check for console errors during export

### Transitions not smooth
- Reduce `canvasWidth` for better performance
- Use simpler transitions
- Disable `drawings` if not needed

```

### references/troubleshooting.md

```markdown
# Slidev Troubleshooting Guide

Common issues and solutions when working with Slidev.

## Development Issues

### Slides Not Updating

**Problem**: Changes to `slides.md` not reflecting in browser

**Solutions**:
1. Hard refresh browser: `Cmd/Ctrl + Shift + R`
2. Clear Vite cache: `slidev --force`
3. Delete `.slidev` directory and restart:
   ```bash
   rm -rf .slidev
   slidev
   ```
4. Check for syntax errors in frontmatter (invalid YAML)

### Port Already in Use

**Problem**: Error: `Port 3030 is already in use`

**Solutions**:
1. Use different port: `slidev --port 8080`
2. Kill process on port 3030:
   ```bash
   lsof -ti:3030 | xargs kill -9
   ```
3. Set default port in `slidev.config.ts`:
   ```typescript
   export default defineConfig({
     port: 8080
   })
   ```

### Hot Reload Not Working

**Problem**: Changes require manual refresh

**Solutions**:
1. Check file watcher limits (Linux):
   ```bash
   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   ```
2. Verify file is saved (check editor auto-save)
3. Try restart: `Ctrl+C` and `slidev` again

### Module Not Found Errors

**Problem**: `Cannot find module '@slidev/cli'` or similar

**Solutions**:
1. Install dependencies: `pnpm install`
2. Clear node_modules: `rm -rf node_modules && pnpm install`
3. Check Node.js version: `node --version` (need >= 18.0)
4. Verify in project directory with `package.json`

## Rendering Issues

### Layout Not Found

**Problem**: Error: `Layout "my-layout" not found`

**Solutions**:
1. Check layout exists in theme or `./layouts/`
2. Verify layout name spelling (case-sensitive)
3. For custom layouts, ensure file is `my-layout.vue` in `./layouts/`
4. Check theme documentation for available layouts

### Images Not Displaying

**Problem**: Images show broken icon or don't load

**Solutions**:
1. Verify path starts with `/` for public folder: `/image.png`
2. Check file exists in `public/` directory
3. Try absolute URL: `https://example.com/image.jpg`
4. Verify file extension is correct
5. Check browser console for 404 errors

### Fonts Not Loading

**Problem**: Custom fonts not appearing

**Solutions**:
1. Check internet connection (for Google Fonts)
2. Verify font name spelling in config:
   ```yaml
   fonts:
     sans: "Inter"  # Exact name
   ```
3. Try different provider: `provider: 'none'` for local fonts
4. Add local fonts to `public/fonts/` and use CSS:
   ```css
   @font-face {
     font-family: 'MyFont';
     src: url('/fonts/myfont.woff2');
   }
   ```

### Components Not Rendering

**Problem**: Vue components show as raw text

**Solutions**:
1. Check component file is in `./components/` directory
2. Verify file name matches component usage (case-sensitive)
3. Ensure component has proper `<template>` structure
4. Check for syntax errors in component
5. Try explicit import if auto-import fails:
   ```markdown
   <script setup>
   import MyComponent from './components/MyComponent.vue'
   </script>
   ```

### Code Blocks Not Highlighting

**Problem**: Code shows without syntax highlighting

**Solutions**:
1. Specify language: ` ```typescript ` not ` ``` `
2. Check language is supported by Shiki
3. Verify no syntax errors in code
4. Clear cache: `slidev --force`

### Mermaid Diagrams Not Rendering

**Problem**: Diagram shows as text or error

**Solutions**:
1. Validate syntax at [mermaid.live](https://mermaid.live)
2. Check for special characters that need escaping
3. Verify Mermaid block starts with ` ```mermaid `
4. Try simpler diagram first to isolate issue
5. Check browser console for errors

## Export Issues

### Export Command Not Found

**Problem**: `slidev export` fails with command not found

**Solutions**:
1. Install playwright: `pnpm add -D playwright-chromium`
2. Verify in project directory
3. Check `package.json` has correct scripts:
   ```json
   {
     "scripts": {
       "export": "slidev export"
     }
   }
   ```

### Export Hangs or Times Out

**Problem**: Export process freezes or times out

**Solutions**:
1. Increase timeout: `slidev export --timeout 60000`
2. Export specific range: `slidev export --range 1-10`
3. Disable Monaco if not needed: `monaco: false` in config
4. Check for infinite animations or loops
5. Try without clicks: `slidev export` (default no clicks)

### PDF Missing Content

**Problem**: Exported PDF missing elements or truncated

**Solutions**:
1. Add wait time: `slidev export --wait 2000`
2. Disable lazy loading: Set `preload: true` on heavy slides
3. Check CSS for `display: none` that should be removed
4. Verify all images loaded before export
5. Try browser export instead of CLI export

### Broken Emojis in PDF

**Problem**: Emojis render as boxes or missing characters

**Solutions**:
1. Install Noto Color Emoji font on system
2. Use images instead of emoji characters
3. Specify font fallback in CSS:
   ```css
   body {
     font-family: Inter, "Noto Color Emoji", sans-serif;
   }
   ```

### PPTX Export Issues

**Problem**: PowerPoint export fails or corrupted

**Solutions**:
1. Update Slidev: `pnpm update @slidev/cli`
2. Simplify slides (remove complex CSS/animations)
3. Export as PDF first to verify content
4. Check compatibility of components used
5. Try smaller slide ranges

## Monaco Editor Issues

### Monaco Not Loading

**Problem**: Code blocks with `{monaco}` don't show editor

**Solutions**:
1. Enable Monaco: `monaco: 'dev'` or `monaco: true` in headmatter
2. Clear cache: `slidev --force`
3. Check browser console for errors
4. Verify TypeScript configuration if using TS

### TypeScript Types Not Working

**Problem**: No IntelliSense or type errors in Monaco

**Solutions**:
1. Set types source: `monacoTypesSource: 'ata'` in frontmatter
2. Add types manually in `setup/monaco.ts`:
   ```typescript
   export default defineMonacoSetup(async (monaco) => {
     monaco.languages.typescript.javascriptDefaults.addExtraLib(
       'declare module "my-module" { ... }',
       'file:///my-module.d.ts'
     )
   })
   ```
3. Check internet connection (for CDN types)
4. Specify additional packages:
   ```yaml
   monacoTypesAdditionalPackages:
     - vue
     - lodash
   ```

### Monaco Running Code Fails

**Problem**: `{monaco-run}` doesn't execute or shows errors

**Solutions**:
1. Check for syntax errors in code
2. Verify browser console for runtime errors
3. Add dependencies in config:
   ```yaml
   monacoRunAdditionalDeps:
     - [email protected]
   ```
4. Test code in browser console first
5. Use try-catch for better error messages

## Animation & Transition Issues

### Click Animations Not Working

**Problem**: `v-click` elements don't appear on click

**Solutions**:
1. Verify syntax: `<div v-click>` or `<v-click>`
2. Check for conflicting CSS (opacity, display)
3. Ensure not in static export mode
4. Test in presenter mode
5. Check browser console for Vue errors

### Transitions Jerky or Slow

**Problem**: Slide transitions lag or stutter

**Solutions**:
1. Reduce `canvasWidth`: `canvasWidth: 800`
2. Use simpler transitions: `transition: fade`
3. Disable drawings if unused: `drawings.enabled: false`
4. Optimize images (compress, WebP format)
5. Limit concurrent animations
6. Test in production build: `slidev build`

### Motion Animations Not Smooth

**Problem**: `v-motion` animations choppy

**Solutions**:
1. Reduce animation complexity
2. Use hardware-accelerated properties (transform, opacity)
3. Avoid animating layout properties (width, height)
4. Test on target presentation device
5. Use spring animations with lower stiffness:
   ```javascript
   const config = {
     x: 0,
     transition: {
       type: 'spring',
       stiffness: 10,
       damping: 15
     }
   }
   ```

## Theme Issues

### Theme Not Applying

**Problem**: Theme setting in frontmatter has no effect

**Solutions**:
1. Install theme: `pnpm add slidev-theme-name`
2. Check theme name spelling (exact match)
3. Verify theme in `node_modules`
4. Try local theme path: `theme: ./my-theme`
5. Clear cache: `slidev --force`

### Theme Colors Wrong

**Problem**: Theme colours different than expected

**Solutions**:
1. Check `colorSchema` setting: `colorSchema: 'light'` or `'dark'`
2. Verify `themeConfig` matches theme's expected format
3. Override in custom CSS if needed
4. Check theme documentation for configuration options

### Theme Layout Missing

**Problem**: Theme's custom layout not available

**Solutions**:
1. Verify theme version supports layout
2. Check theme documentation for layout names
3. Inspect `node_modules/slidev-theme-*/layouts/`
4. Create custom layout if needed in `./layouts/`

## Build & Deployment Issues

### Build Fails

**Problem**: `slidev build` command fails

**Solutions**:
1. Check Node.js version: >= 18.0
2. Clear cache: `rm -rf .slidev dist`
3. Install dependencies: `pnpm install`
4. Check for syntax errors in slides
5. Review build output for specific errors
6. Try without optimisations: `slidev build --no-optimize`

### Static Site Not Working

**Problem**: Built site doesn't work when deployed

**Solutions**:
1. Set base path: `slidev build --base /slides/`
2. Check asset paths are relative
3. Verify server serves SPA correctly (fallback to index.html)
4. Test locally: `npx serve dist`
5. Check browser console for errors

### Assets Not Loading After Build

**Problem**: Images/videos 404 in production

**Solutions**:
1. Verify files in `public/` directory
2. Use absolute paths starting with `/`
3. Check base URL configuration
4. Ensure build includes public assets
5. Test with `npx serve dist` before deploying

## Performance Issues

### Slow Slide Load

**Problem**: Slides take long time to load/transition

**Solutions**:
1. Optimize images (compress, appropriate size)
2. Lazy load heavy slides: `preload: false`
3. Reduce `canvasWidth`
4. Disable unused features:
   ```yaml
   monaco: false
   drawings.enabled: false
   ```
5. Limit number of slides with heavy content

### High Memory Usage

**Problem**: Browser uses excessive memory

**Solutions**:
1. Reduce image sizes
2. Limit Monaco editors on single slide
3. Close other browser tabs
4. Use production build: `slidev build`
5. Disable dev tools when not needed

## Remote Control Issues

### Remote Not Connecting

**Problem**: Remote control URL doesn't work

**Solutions**:
1. Verify both devices on same network
2. Check firewall/network settings
3. Try different password: `slidev --remote newpass`
4. Use IP address instead of localhost
5. Check browser console for WebSocket errors

### Remote Sync Issues

**Problem**: Remote device out of sync with presenter

**Solutions**:
1. Refresh remote device browser
2. Check network stability
3. Verify `syncAll: true` in drawings config if using drawings
4. Test with simpler presentation first
5. Check for JavaScript errors on remote device

## Diagnostic Commands

### Check Slidev Version
```bash
pnpm list @slidev/cli
```

### Clear All Caches
```bash
rm -rf .slidev node_modules/.vite
pnpm install
slidev --force
```

### Verbose Logging
```bash
slidev --log debug
```

### Test Build
```bash
slidev build --no-bundle
npx serve dist
```

## Getting Help

If issues persist:

1. **Check Documentation**: https://sli.dev
2. **GitHub Issues**: Search existing issues at https://github.com/slidevjs/slidev/issues
3. **Discord Community**: https://chat.sli.dev
4. **Stack Overflow**: Tag with `slidev`

### Reporting Bugs

Include in bug report:
- Slidev version (`pnpm list @slidev/cli`)
- Node.js version (`node --version`)
- Operating system
- Minimal reproduction (simplified `slides.md`)
- Error messages (full stack trace)
- Browser console output (if relevant)
- Steps to reproduce

### Creating Minimal Reproduction

```yaml
---
theme: default
---

# Test Slide

This is a minimal test to reproduce the issue.

<!-- Describe the issue here -->
```

Save as `test-slides.md` and run: `slidev test-slides.md`

```