Slidev

Slidev Presentation Assistant

This skill helps create and manage presentations using Slidev, a developer-focused presentation framework that combines markdown simplicity with web technology power.

Content Density Rules (HARD LIMITS)

These limits prevent content overflow and ensure readability. Based on cognitive science (Miller's Law, dual-channel processing) and established across multiple AI-assisted Slidev workflows.

Per-Slide Budgets

Content Density by Slide Type

The Split-Don't-Compress Rule

When content doesn't fit:

• ALWAYS split into additional slides
• ALWAYS move details to presenter notes (<!-- ... -->) or backup slides
• NEVER compress or shrink font below minimums to cram more content
• NEVER reduce body font below 18pt or heading font below 24pt

Font Size Minimums

Limit to 2 font families maximum. Use sans-serif for body text on screens.

Overflow Prevention Toolkit

Slidev's default canvas is 980x552px (16:9). Content must fit within these dimensions.

Canvas Size Configuration (Global Headmatter)

---
canvasWidth: 980
aspectRatio: 16/9
---

Per-Slide Zoom (Frontmatter)

Scale down an entire slide when content is slightly too large. Prefer this over reducing font sizes:

---
zoom: 0.8
---
# This slide's content is rendered at 80% scale

Only use for minor adjustments (0.8-0.95). If you need zoom below 0.8, the slide has too much content — split it.

<Transform> Component (Element-Level Scaling)

Scale specific elements without affecting the rest of the slide:

<Transform :scale="0.7" origin="top center">
  <div>This content is 70% of normal size</div>
</Transform>

<AutoFitText> Component

Built-in component where font size automatically adapts to fit the container:

<AutoFitText>
  Text that automatically shrinks to fit available space
</AutoFitText>

Code Block maxHeight (Prevents Code Overflow)

Built-in feature to constrain code blocks with scrolling:

```ts {2|3|7|12}{maxHeight:'200px'}
// Long code that would overflow the slide
// Gets a scrollbar instead of pushing content off-screen
function example() {
  const a = 1
  const b = 2
  const c = 3
  const d = 4
  const e = 5
  const f = 6
  return a + b + c + d + e + f
}
```

Constraining Diagrams

Wrap Mermaid diagrams to prevent overflow:

<div class="overflow-hidden max-h-[400px] flex justify-center">

```mermaid
graph TD
    A --> B --> C

Progressive Disclosure with v-click

Instead of showing all bullets at once (overflow risk), reveal incrementally. Hidden elements use opacity: 0 and still occupy space (no layout shift):

<v-clicks>

- Point 1
- Point 2
- Point 3
- Point 4

</v-clicks>

This keeps visible element count within cognitive bounds at any moment.

CSS Rules for Slidev

Critical: Always Scope Under .slidev-layout

Unscoped CSS breaks presenter mode and overview panels. This is the #1 CSS mistake in Slidev:

<!-- CORRECT: Scoped to slide content -->
<style>
.slidev-layout { overflow: hidden; }
.slidev-layout h1 { font-size: 2.5rem; }
</style>

<!-- ALSO CORRECT: Per-slide scoped style -->
<style scoped>
h1 { font-size: 2rem; }
</style>

<!-- WRONG: Will break presenter mode UI -->
<style>
h1 { font-size: 2rem; }
.grid { align-items: center; }
</style>

Recommended Global style.css

Place in project root alongside slides.md:

/* Prevent content from overflowing slide boundaries */
.slidev-layout {
  overflow: hidden;
}

/* Allow code blocks to scroll when they exceed available space */
.slidev-layout .slidev-code-wrapper {
  overflow: auto !important;
  max-height: 80%;
}

/* Ensure code content itself can scroll horizontally */
.slidev-layout .slidev-code {
  overflow: auto !important;
}

Use overflow: hidden for hard-clip (good for export/PDF) or overflow: auto for scrolling (good for live presentations).

Per-Slide CSS Targeting

Target specific slides by page number:

.slidev-page-2 {
  zoom: 90%;
}

.slidev-page-5 .slidev-layout {
  overflow-y: auto;
}

UnoCSS Utility Classes Reference

Slidev uses @unocss/preset-wind3 (Tailwind-compatible). Key classes for layout control:

Apply to slides via frontmatter or inline:

---
class: text-sm overflow-hidden
---

<div class="grid grid-cols-2 gap-4">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

UnoCSS --uno: Directive in CSS

.slidev-layout {
  --uno: px-14 py-10 text-[1.1rem];
}

Quick Start

Creating a New Presentation

# Initialize new Slidev project
npm init slidev@latest

# Or use existing project
npm install @slidev/cli --save-dev

Basic Slide Structure

---
theme: seriph
background: https://source.unsplash.com/collection/94734566/1920x1080
---

# Welcome to Slidev

Presentation slides for developers

---

# Agenda

- Introduction
- Code Examples
- Live Demo
- Q&A

---
layout: two-cols
---

# Two Column Layout

::left::

Left side content

::right::

Right side content

Core Commands

Development

slidev                    # Start dev server (default: slides.md)
slidev slides.md -o       # Start and open in browser
slidev --port 3030        # Use custom port

Building & Exporting

slidev build              # Build static SPA
slidev export             # Export to PDF (default)
slidev export --format pptx    # Export to PowerPoint
slidev export --format png     # Export as PNG images
slidev export --with-clicks    # Include animation steps
slidev export --range 1,4-8    # Export specific slides
slidev export --per-slide      # Per-slide rendering (includes backgrounds)

Export Verification

Automated Content Fit Verification (Recommended)

For comprehensive content verification, use the specialized agent:

# Claude Code will invoke the slidev-content-verifier agent
# This agent will automatically:
# 1. Export slides to PNG with proper wait times
# 2. Analyze each slide systematically
# 3. Check for all types of content issues
# 4. Provide specific fix recommendations

To use the agent, simply ask Claude Code:

• "Verify that all slide content fits properly"
• "Check my slides for content cutoffs"
• "Run content fit verification on the presentation"

The agent uses the workflow described below and provides a detailed report with specific fixes.

slidev-overflow-checker (Pixel-Level CI Tool)

A Playwright-based CLI tool that renders slides in a real browser and detects pixel-level overflow. Detects three issue types: text-overflow, element-overflow, and unintended scrollbars.

# Install
npm install -g slidev-overflow-checker

# Start dev server first, then in another terminal:
slidev-overflow-checker --url http://localhost:3030

# CI integration (fails build on overflow)
slidev-overflow-checker --url http://localhost:3030 --fail-on-issues

# Check specific slides
slidev-overflow-checker --url http://localhost:3030 --pages 1-10

# Verbose output with source line mapping
slidev-overflow-checker --url http://localhost:3030 --verbose --project ./

GitHub Actions integration:

- name: Check slide overflow
  run: |
    npx slidev dev &
    sleep 10
    slidev-overflow-checker --url http://localhost:3030 --fail-on-issues

Claude Code command integration:

mkdir -p .claude/commands
curl -o .claude/commands/fix-slidev-overflow.md \
  https://raw.githubusercontent.com/mizuirorivi/slidev-overflow-checker/master/templates/fix-slidev-overflow.md
# Then invoke with: /fix-slidev-overflow ./

Source: mizuirorivi/slidev-overflow-checker

Manual Content Fit Verification Workflow

For manual verification or understanding the process, use PNG export with direct analysis:

# 1. Export slides to PNG with proper wait times
slidev export --format png --wait 2000 --timeout 120000

# Export specific slides for quick iteration
slidev export --format png --range 5,8,12 --wait 2000

# 2. List exported PNGs
ls -la slides-export/

# 3. Use Read tool to analyze each PNG directly
# The Read tool can display PNG images for visual inspection
# Check each slide systematically

Analysis Workflow with Read Tool:

# After export, use Read tool on each PNG to verify:
# - All text is visible and not cut off at edges
# - Code blocks are fully displayed with all lines
# - Bullet points and list items are complete
# - Headers and footers are within slide bounds
# - Images and diagrams are not clipped
# - Long URLs or file paths aren't truncated
# - Mermaid diagrams render completely
# - Tables fit within slide width

# Example verification process:
# Read slides-export/001.png - Check title slide
# Read slides-export/002.png - Verify agenda items all visible
# Read slides-export/003.png - Confirm code block not cut off
# Read slides-export/004.png - Check diagram fully renders

Content Fit Checklist: When analyzing each PNG:

• Top margin: Header/title not cut off
• Bottom margin: Footer/content fully visible
• Left edge: No text clipping on bullet points or code
• Right edge: Long lines don't exceed slide width
• Code blocks: All lines visible, no vertical scroll needed
• Lists: All items and sub-items render completely
• Diagrams: Full diagram visible, no edge clipping
• Element count: No more than 6 elements visible
• Font sizes: Body text appears >= 18pt equivalent

Fixing Content That Doesn't Fit:

# Ordered by preference (best first):

# 1. Split into multiple slides (PREFERRED)
# Move excess content to a new slide

# 2. Move details to presenter notes
<!--
Detailed explanation goes here, not on the slide
-->

# 3. Use per-slide zoom (minor adjustments only)
---
zoom: 0.9
---

# 4. Use two-column layout to spread horizontally
---
layout: two-cols
---

# 5. Use maxHeight on code blocks
```ts {all}{maxHeight:'200px'}
long code here

6. Apply text-sm class (stays above 18pt minimum)

class: text-sm

7. Scale specific elements with Transform

8. Use AutoFitText for text that must fit

Timing and Rendering Issues

To ensure proper rendering before export:

# Add wait time for animations/content loading
slidev export --wait 2000

# Use specific wait conditions for network resources
slidev export --wait-until networkidle

# Increase timeout for complex slides with heavy content
slidev export --timeout 120000

# Combine for best results
slidev export --format png --wait 3000 --wait-until networkidle --timeout 120000

Custom Layouts with Overflow Protection

Place .vue files in a layouts/ directory alongside slides.md.

Scrollable Layout

layouts/scrollable.vue:

<template>
  <div class="slidev-layout scrollable-layout">
    <slot />
  </div>
</template>

<style scoped>
.scrollable-layout {
  overflow-y: auto;
  max-height: 100%;
  padding: 2rem;
}
</style>

Usage:

---
layout: scrollable
---
# Slide with lots of content that can scroll

Safe Content Layout (Flexbox with Overflow Guard)

layouts/safe-content.vue:

<template>
  <div class="slidev-layout safe-content">
    <div class="content-wrapper">
      <slot />
    </div>
  </div>
</template>

<style scoped>
.safe-content {
  padding: 2rem 3rem;
  height: 100%;
  display: flex;
  flex-direction: column;
}

.content-wrapper {
  flex: 1;
  overflow-y: auto;
  max-height: calc(100% - 2rem);
}
</style>

Essential Features

Code Highlighting

```ts {2,3|5|all}
function add(a: number, b: number): number {
  // This line highlights first
  return a + b
}
console.log(add(1, 2)) // Then this
```

Components & Interactivity

<Counter :count="10" />

<Tweet id="1390115482657726468" />

<Youtube id="eW7v-2ZKZOU" />

Presenter Notes

# My Slide

Content visible to audience

<!--
Presenter notes here
- Reminder point 1
- Key talking point
- Detailed explanation that would clutter the slide
-->

Use presenter notes aggressively to keep slides clean. Any text that explains or elaborates should go in notes, not on the slide.

Animations

# Animations

<v-clicks>

- First item appears
- Second item appears
- Third item appears

</v-clicks>

<v-click>

This appears on click

</v-click>

Note: v-click uses opacity: 0 + pointer-events: none by default. Hidden elements still occupy space in the layout (no layout shift). If total content exceeds slide boundaries, add overflow: hidden to the slide.

Advanced Features

Diagrams with Mermaid

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do this]
    B -->|No| D[Do that]
```

LaTeX Math

$\sqrt{3x-1}+(1+x)^2$

$$
\begin{array}{c}
\nabla \times \vec{\mathbf{B}} = \mu_0 \vec{\mathbf{J}}
\end{array}
$$

Custom Layouts

---
layout: center
class: text-center
---

# Centered Content

---
layout: image-right
image: ./path/to/image.png
---

# Content with Image

Text on the left, image on right

Built-in Layouts Reference

Frontmatter Configuration

---
theme: default          # Theme name
title: My Presentation  # HTML title
titleTemplate: '%s - Slidev'  # Title template
canvasWidth: 980        # Canvas width in px (default: 980)
aspectRatio: 16/9       # Aspect ratio (default: 16/9)
info: |                 # Info for overview
  ## My Presentation
  Learn about...
author: Your Name       # Presenter name
keywords: slidev,presentation  # SEO keywords
favicon: favicon.ico    # Custom favicon
highlighter: shiki      # Code highlighter
drawings:
  persist: false        # Persist drawings
transition: slide-left  # Slide transition
css: unocss            # CSS framework
fonts:
  sans: Roboto         # Custom fonts
  mono: Fira Code
---

Theme Management

# Install themes
npm install @slidev/theme-seriph
npm install @slidev/theme-apple-basic

# Use in frontmatter
---
theme: seriph
---

Markdownlint Configuration

Slidev's multi-frontmatter syntax (slide separators ---) can be corrupted by markdown linters. Add this .markdownlint.json to prevent issues:

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

Common Workflows

Creating Technical Presentation

1. Initialize project with appropriate theme
2. Plan content with density limits in mind (max 6 elements, max 50 words per slide)
3. Structure with one idea per slide
4. Add code examples with highlighting and maxHeight
5. Include diagrams with height constraints
6. Move detailed explanations to presenter notes
7. Test presenter mode
8. Run overflow verification (agent or slidev-overflow-checker)
9. Export to PDF for sharing

Live Coding Demo

---
layout: iframe
url: https://stackblitz.com/edit/vue
---

Recording Presentation

# Built-in recording (with camera)
slidev --record

# Export recording
slidev export --format webm

Best Practices

Slide Design

• ONE idea per slide (split if multiple)
• MAX 6 elements per slide (bullets + images + code blocks combined)
• MAX 50 words body text per slide
• Use phrases not sentences for bullets (3-6 words each)
• Titles should be assertions, not labels ("API Reduces Latency 3x" not "API Performance")
• Use presenter notes aggressively for detailed explanations
• Use v-click for progressive disclosure on slides with 4+ bullets

Content Fitting Priority

When content overflows, fix in this order:

1. Split into multiple slides
2. Move details to presenter notes
3. Use zoom: 0.9 frontmatter (minor adjustment)
4. Use two-column layout
5. Apply maxHeight to code blocks
6. Use <Transform :scale="0.8"> on specific elements
7. Apply class: text-sm (but respect font minimums)

Performance

• Optimize images (use appropriate formats)
• Lazy load heavy components
• Test exports early to catch rendering issues
• Use --wait parameter for animation-heavy slides

Accessibility

• Body text minimum 18pt, headings minimum 24pt
• Contrast ratio minimum 4.5:1 (WCAG AA)
• Use colorblind-safe palette (Blue + Orange as default)
• Provide alt text for images
• Ensure sufficient color contrast
• Test keyboard navigation
• Include slide numbers for reference
• Limit to 2 font families

Troubleshooting

Export Issues

Text cut off in PDF:

slidev export --wait 3000 --timeout 120000

Content overflows in export but looks fine in browser: Add global overflow protection:

/* style.css */
.slidev-layout {
  overflow: hidden;
}

Missing emojis in export:

# Install emoji font (Linux)
sudo apt-get install fonts-noto-color-emoji

PPTX text not selectable: This is a known limitation - PPTX slides export as images.

Layout Issues

Code block pushes content off slide:

```ts {all}{maxHeight:'200px'}
// Code gets a scrollbar instead of overflowing
```

Diagram too large:

<div class="overflow-hidden max-h-[350px]">

```mermaid
graph TD
    A --> B

Custom CSS breaks presenter mode: Always scope CSS — use <style scoped> or prefix selectors with .slidev-layout.

Development Issues

Port already in use:

slidev --port 3031

Hot reload not working:

# Clear cache and restart
rm -rf node_modules/.vite
slidev --force

Quick Reference

Keyboard Shortcuts

• Space/Right: Next slide
• Left: Previous slide
• G: Go to slide
• O: Toggle overview
• D: Toggle dark mode
• F: Toggle fullscreen
• P: Toggle presenter mode
• C: Show camera view
• R: Start recording

Directory Structure

my-presentation/
   slides.md          # Main presentation file
   style.css          # Global styles (scope under .slidev-layout)
   public/           # Static assets
   components/       # Custom Vue components
   layouts/          # Custom layouts (overflow-safe .vue files)
   styles/           # Additional styles (index.css auto-loaded)
   .slidev/          # Generated files

Examples

Complete Slide with Features

---
layout: two-cols
transition: fade-out
---

# Advanced Example

<v-clicks>

- Automated animations
- Code with highlighting
- Mathematical equations

</v-clicks>

::right::

```js {2|4|6}
const greeting = 'Hello'
console.log(greeting)

const name = 'Slidev'
console.log(name)

console.log(`${greeting} ${name}!`)

$E = mc^2$

### Overflow-Safe Code Slide

````markdown
---
zoom: 0.95
---

# Implementation Details

```ts {2|5|8}{maxHeight:'300px'}
class DataProcessor {
  private cache = new Map<string, Result>()

  async process(input: Input): Promise<Result> {
    if (this.cache.has(input.key)) {
      return this.cache.get(input.key)!
    }
    const result = await this.transform(input)
    this.cache.set(input.key, result)
    return result
  }
}

### Dense Content with Grid Layout

```markdown
---
class: text-sm
---

# Feature Comparison

<div class="grid grid-cols-2 gap-4">
<div>

### Option A
- Fast startup
- Low memory
- Simple config

</div>
<div>

### Option B
- Better throughput
- Plugin ecosystem
- Auto-scaling

</div>
</div>

<!--
Detailed comparison notes for presenter...
-->
```

For additional customization and advanced features, refer to the [Slidev documentation](https://sli.dev).

## Sources

Improvements informed by:
- [rhuss/cc-slidev](https://github.com/rhuss/cc-slidev) - Evidence-based content limits and design guardrails
- [mizuirorivi/slidev-overflow-checker](https://github.com/mizuirorivi/slidev-overflow-checker) - Playwright-based overflow detection
- [antfu/skills](https://github.com/antfu/skills/tree/main/skills/slidev) - Official Slidev AI skill
- [clearfunction/cf-devtools](https://github.com/clearfunction/cf-devtools) - Markdownlint configuration
- [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides) - Viewport fitting rules
- [Slidev Official Docs](https://sli.dev) - Canvas size, zoom, Transform, AutoFitText, maxHeight, layouts
- [Slidev GitHub Issues](https://github.com/slidevjs/slidev/issues/2446) - CSS scoping requirements

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kaovilai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->