Creating Slidev Presentations

Creating Slidev Presentations

Slidev is a web-based slide maker designed for developers. Write slides in Markdown, leverage Vue 3 components, and export to PDF, PPTX, or PNG. Ideal for technical presentations, demos, and interactive content.

Quick Start

Create a New Project

npm init slidev
# or
pnpm create slidev

Basic Commands

npm run dev        # Start development server (http://localhost:5173)
npm run build      # Build as static site
npm run export     # Export to PDF, PPTX, or PNG
npm run format     # Format slides.md

Slidev Markdown Structure

File Organization

• slides.md - Main presentation file (default)
• public/ - Static assets (images, files)
• package.json - Dependencies and scripts

Slide Separators

Use --- with blank lines to separate slides:

---
layout: cover
---

# Title Slide

---

# Content Slide

Frontmatter Configuration

Headmatter (First Slide)

Configure the entire presentation in the first slide's frontmatter:

---
theme: default
title: My Presentation
info: Presentation description
author: Your Name
highlighter: shiki
lineNumbers: true
mdc: true
css: unocss
shiki:
  theme: nord
layout: cover
---

Per-Slide Frontmatter

Configure individual slides:

---
layout: two-cols
background: url('/bg.jpg')
clicks: 3
transition: slide-left
---

Key Frontmatter Options

Markdown Features

Code Blocks with Syntax Highlighting

\`\`\`typescript async function agent() { const skills = await Skill.all(); }
\`\`\`

\`\`\`python {1,3}

# Line 1 highlighted

print("not highlighted") print("highlighted") \`\`\`

Scoped CSS

Add styles to specific slides:

<style scoped>
h1 {
  color: #58A6FF;
}
</style>

Vue Components

Use Vue 3 components in slides:

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<template>
  <button @click="count++">
    Count: {{ count }}
  </button>
</template>

Presenter Notes

Add notes visible only to presenter:

---
layout: cover
---

# Title Slide

<!-- This is a presenter note, not shown to audience -->

Common Layouts

Cover Slide

---
layout: cover
---

# My Presentation

Title + Content

---
layout: default
---

# Section Title

- Bullet point 1
- Bullet point 2

Two Columns

---
layout: two-cols
---

::left::
# Left Column
Content

::right::
# Right Column
Content

Image Right

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

# Title

Content on left, image on right

Center Layout

---
layout: center
---

# Centered Content

Styling Slides

Inline Styles

<div style="color: #58a6ff; font-size: 24px">
  Styled text
</div>

CSS Classes

<div class="text-blue-500 text-xl font-bold">
  Styled with UnoCSS
</div>

Global Styles

Add to headmatter <style> block:

---

## ...

<style>
.slidev-layout {
  background: #0D1117 !important;
}

h1 {
  color: #F8FAFC !important;
}
</style>

Advanced Features

Diagrams with Mermaid

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

LaTeX Math

$$
E = mc^2
$$

Inline: $\alpha = \frac{\beta}{\gamma}$

Animations & Clicks

---
clicks: 3
---

# Title

<v-click>This appears on click 1</v-click>
<v-click>This appears on click 2</v-click>

Draggable Elements

<div v-drag="'id-key'" style="position: absolute;">
  Drag me around
</div>

Exporting Presentations

Export to PDF

npm run export -- --format pdf
npm run export -- --format pdf --output my-slides.pdf

Export to PPTX

npm run export -- --format pptx
# All slides exported as images for compatibility

Export to PNG

npm run export -- --format png
# Creates PNG for each slide in dist/

Export with Animations

npm run export -- --format pdf --with-clicks
# Exports multiple pages per slide with animation steps

Export Options

# Specific slide range
npm run export -- --range 1,3-5,10

# Dark mode
npm run export -- --dark

# Increase timeout for large presentations
npm run export -- --timeout 60000

# Add table of contents
npm run export -- --with-toc

Configuration File (slidev.config.ts)

Create slidev.config.ts for advanced configuration:

import { defineConfig } from "@slidev/cli";

export default defineConfig({
  // Enable/disable features
  monaco: true,
  twoslash: true,
  recorder: true,

  // Export settings
  export: {
    format: "pdf",
    timeout: 30000,
    dark: false,
  },

  // Theme configuration
  themeConfig: {
    primary: "#5d8392",
  },
});

Best Practices

Content Organization

• Keep headmatter clean and focused
• Use descriptive slide titles
• One idea per slide
• Limit bullet points to 3-5 per slide

Code in Presentations

• Use syntax highlighting with language specification
• Highlight important lines with {1,3}
• Show complete, runnable examples
• Explain code before revealing it with <v-click>

Styling

• Use consistent color scheme
• Define global styles in headmatter
• Use scoped styles for slide-specific customization
• Test dark mode for exports

Interactive Elements

• Use Vue components for dynamic content
• Add click animations for complex topics
• Include live code examples with Monaco editor
• Record demos when presenting remotely

Accessibility

• Use semantic HTML elements
• Ensure sufficient color contrast
• Provide alt text for images
• Test with screen readers

Common Issues

Blank First Page

Ensure headmatter is properly formatted and includes layout: cover if needed. First --- marks headmatter start, second --- marks headmatter end.

Code Block Rendering Issues

• Verify language is specified: ```typescript
• Ensure blank lines around code blocks
• Use proper escaping for special characters

Export Failures

• Install Playwright: npm install -D playwright-chromium
• Use modern Chromium browser
• Increase timeout for large presentations
• Check for missing fonts or images

Styling Not Applied

• Use !important for global overrides
• Scope CSS with <style scoped>
• Check CSS specificity
• Clear browser cache

Resources

• Official Docs: https://sli.dev
• GitHub: https://github.com/slidevjs/slidev
• Discord: https://chat.sli.dev
• Examples: https://sli.dev/resources/theme-gallery

Integration with Development Workflow

Version Control

• Commit slides.md to git
• Ignore dist/, node_modules/, .git-pptx/
• Use .gitignore:

  dist/
  node_modules/
  *.pdf
  *.pptx
  *.png

CI/CD Export

# GitHub Actions example
- name: Export slides to PDF
  run: npx slidev export --format pdf

Embedding in Web Projects

Build as static site and host:

npm run build
# Deploy dist/ folder to web server

Example: Technical Presentation Template

---
theme: default
background: "#0D1117"
title: Agent Skills Integration
author: Your Name
highlighter: shiki
layout: cover
---

<style>
.slidev-layout {
  background: #0D1117 !important;
}

h1, h2, h3 {
  color: #F8FAFC !important;
}

p, li {
  color: #E2E8F0 !important;
}
</style>

# Agent Skills Integration

Building reusable skill components

---

# Overview

- Skill definition and structure
- Automatic discovery
- System prompt injection
- Tool registration

---

# Implementation

\`\`\`typescript export function createSkillTool(skills: SkillInfo[]) { return
tool({ description: 'Load a skill', execute: async ({ name }) => { return await
Skill.load(name); }, }); } \`\`\`

---
layout: center
---

# Questions?

Workflow for Creating Professional Presentations

1. Plan: Outline content and structure
2. Draft: Write slides.md with basic content
3. Style: Add CSS, themes, and layout configuration
4. Animate: Add interactions and animations
5. Test: Preview in browser, test exports
6. Export: Generate PDF/PPTX for distribution
7. Present: Use Slidev dev server with presenter mode

FAQ - Common Pitfalls & Solutions

Blank First Page Issue

Problem: First slide appears blank even with content defined.

Root Cause:

• Empty space between headmatter closing --- and content
• Headmatter not properly containing opening content
• Missing layout configuration in headmatter

Solution:

---
theme: default
title: My Presentation
layout: cover
---

# Title Content Starts Here Immediately

No blank lines between --- and content!

Key Points:

• Headmatter must have layout: cover for first slide to display properly
• Content starts immediately after closing ---
• Do NOT have blank lines between --- and # heading
• The first slide content is part of the headmatter, not a separate slide

Markdown Code Blocks in HTML Containers

Problem: Code blocks don't render when nested inside HTML <div> elements.

<!-- ❌ WRONG -->
<div class="code-container">
  <div class="code-content">
```markdown
const x = 1;

</div>
</div>

<!-- ✅ CORRECT -->

<div class="code-container">
  <div class="code-content">

```markdown const x = 1; ```

</div>
</div>
```

Root Cause: Slidev's markdown parser requires blank lines around code blocks, even inside HTML.

Solution:

• Add blank line BEFORE opening backticks
• Add blank line AFTER closing backticks
• Indent appropriately for readability

Code Block Background Colors Not Working

Problem: Global <style> color overrides for code blocks are ignored.

Root Cause: Shiki syntax highlighter applies inline styles with higher specificity, and MDC/Vue markdown rendering creates additional nested elements.

Solution: Use !important in CSS rules:

<style>
.code-content {
  padding: 16px 20px;
  background: #0F172A !important;
  color: #F1F5F9;
}

.code-content pre {
  background: #0F172A !important;
}

.code-content code {
  background: #0F172A !important;
  color: #F1F5F9 !important;
}
</style>