@sp-days-framework/docusaurus-plugin-slidev

Seamlessly integrate Slidev presentations into your Docusaurus site with automatic builds, preview thumbnails, and a beautiful overview page.

Features

• Automatic Discovery - Scans directories for Slidev markdown files and builds them automatically
• Interactive Overview Page - Auto-generated gallery with presentation previews, metadata, and sorting
• Zero-Config Setup - Works out of the box with sensible defaults
• Theme Support - Global or per-presentation theme configuration with automatic validation

Installation

npm install @sp-days-framework/docusaurus-plugin-slidev

Quick Start

1. Add to Docusaurus Config

// docusaurus.config.ts
import type { Config } from "@docusaurus/types";

const config: Config = {
  // Ensure staticDirectories includes 'static'
  staticDirectories: ["static"],

  plugins: ["@sp-days-framework/docusaurus-plugin-slidev"],

  themeConfig: {
    navbar: {
      items: [{ to: "/slidev", label: "Presentations", position: "left" }],
    },
  },
};

export default config;

2. Create Your First Presentation

Create slidev/introduction.md in your Docusaurus project:

---
title: Introduction to Our Product
description: A comprehensive overview of features and benefits
author: Your Name
theme: default
---

# Welcome!

This is my first slide.

---

3. Build and View

npm run build
npm run serve

Visit http://localhost:3000/slidev to see your presentation overview!

Usage

Basic Configuration

The plugin works with zero configuration, but you can customize it:

import type { PluginOptions } from "@sp-days-framework/docusaurus-plugin-slidev";

const config: Config = {
  plugins: [
    [
      "@sp-days-framework/docusaurus-plugin-slidev",
      {
        sourceDir: "./slidev",
        outputDir: "slides",
        overviewPath: "/presentations",
        overviewTitle: "Our Presentations",
        overviewTagline: "Browse our collection of interactive slides",
        download: true,
        buildTimeout: 90,
      } satisfies PluginOptions,
    ],
  ],
};

Organizing Presentations

Organize presentations in subdirectories for better structure:

slidev/
├── workshop/
│   ├── introduction.md
│   └── advanced.md
├── training/
│   ├── basics.md
│   └── best-practices.md
└── conference/
    └── keynote.md

Each presentation gets a unique URL based on its path:

• workshop/introduction.md → /slides/workshop-introduction/
• training/basics.md → /slides/training-basics/

Per-Presentation Themes

Specify a theme in the frontmatter:

---
title: My Presentation
theme: "@slidev/theme-seriph"
---

Or set a global theme in plugin options:

{
  theme: '@slidev/theme-seriph', // Applied to all presentations
}

Note: Make sure to install the theme package:

npm install @slidev/theme-seriph

Frontmatter Options

Slidev plugin support the current frontmatter configuration:

---
title: Advanced Topics
description: Deep dive into advanced features
author: Jane Doe
---

See Slidev documentation for all available options.

Configuration

| Option | Type | Default | Description | | ----------------- | --------- | ------------------------------------- | ------------------------------------------------------------------ | | sourceDir | string | './slidev' | Directory to scan for Slidev markdown files | | outputDir | string | 'slides' | Output directory inside static/ for built presentations | | theme | string | undefined | Global theme override for all presentations | | download | boolean | false | Enable PDF download functionality (requires playwright-chromium) | | overviewPath | string | '/slidev' | URL path for the auto-generated overview page | | overviewTitle | string | 'Slidev Presentations' | Custom title for the overview page | | overviewTagline | string | 'Interactive presentation overview' | Custom tagline/description for the overview page | | id | string | 'default' | Plugin ID for multiple instances | | buildTimeout | number | 60 | Timeout in seconds for building each presentation (10-600) | | verbose | boolean | false | Enable verbose logging for Slidev build output |

Advanced Usage

Multiple Plugin Instances

Run multiple instances with different configurations:

{
  plugins: [
    [
      '@sp-days-framework/docusaurus-plugin-slidev',
      {
        id: 'workshops',
        sourceDir: './workshops',
        outputDir: 'workshop-slides',
        overviewPath: '/workshops',
        overviewTitle: 'Workshop Materials',
      },
    ],
    [
      '@sp-days-framework/docusaurus-plugin-slidev',
      {
        id: 'training',
        sourceDir: './training',
        outputDir: 'training-slides',
        overviewPath: '/training',
        overviewTitle: 'Training Courses',
      },
    ],
  ],
}

Development vs Production

Development Mode (npm run start)

• Presentations are not built
• Overview page shows "Build Required" badges
• Preview thumbnails show placeholder icons
• Faster startup time for development

Production Mode (npm run build)

• All presentations are automatically built
• Overview page shows interactive preview thumbnails
• Presentations are fully functional

Troubleshooting

"Slidev CLI not found" Error

Install Slidev and required dependencies:

npm install @slidev/cli @slidev/theme-default vue

Theme Not Found

If using a custom theme, install it first:

npm install @slidev/theme-seriph

Then reference it in frontmatter or plugin config:

---
theme: "@slidev/theme-seriph"
---

Build Timeout

Increase the timeout for complex presentations:

{
  buildTimeout: 180, // 3 minutes
}

Presentations Not Showing

1. Ensure staticDirectories: ['static'] is in your Docusaurus config
2. Run npm run build (not just npm start)
3. Check that .md files are in the correct sourceDir
4. Verify frontmatter is valid YAML

Preview Thumbnails Not Loading

Preview thumbnails only work in production mode after building. In development, placeholder icons are shown instead.

How It Works

1. Scan Phase - Plugin scans sourceDir for .md files recursively
2. Extract Metadata - Frontmatter is parsed from each file (title, description, theme, author)
3. Build Phase - In production, Slidev builds each presentation to static/outputDir/
4. Generate Routes - Overview page route is registered at overviewPath
5. Render - Overview page displays all presentations with previews and metadata

TypeScript Support

The plugin includes full TypeScript definitions:

import type {
  PluginOptions,
  PresentationMetadata,
  PluginContentData,
  SlidevFrontmatter,
} from "@sp-days-framework/docusaurus-plugin-slidev";