# @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

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

## Quick Start

### 1. Add to Docusaurus Config

```ts
// 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:

```md
---
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

```bash
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:

```ts
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:

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

Or set a global theme in plugin options:

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

**Note:** Make sure to install the theme package:

```bash
npm install @slidev/theme-seriph
```

### Frontmatter Options

Slidev plugin support the current frontmatter configuration:

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

See [Slidev documentation](https://sli.dev/guide/syntax.html#frontmatter) 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:

```ts
{
  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:

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

### Theme Not Found

If using a custom theme, install it first:

```bash
npm install @slidev/theme-seriph
```

Then reference it in frontmatter or plugin config:

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

### Build Timeout

Increase the timeout for complex presentations:

```ts
{
  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:

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