--- sidebar_position: 1.2 sidebar_custom_props: section: "Setup" section_position: 1 --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; # Advanced Configuration ## All Plugin Options | Option | Type | Default | Description | | ---------------------- | ---------- | ------------------------------------- | ---------------------------------------------------------------------- | | `path` | `string` | `'./slidev'` | Directory to scan for Slidev markdown files (also determines URL path) | | `theme` | `string` | `undefined` | Global theme override for all presentations | | `download` | `boolean` | `false` | Enable PDF download functionality | | `routeBasePath` | `string` | `'/slidev'` | URL path for the auto-generated overview page | | `pageTitle` | `string` | `'Slidev Presentations'` | Custom title for the overview page | | `pageTagline` | `string` | `'Interactive presentation overview'` | Custom tagline/description for the overview page | | `id` | `string` | `'default'` | Plugin ID for multiple instances | | `buildTimeout` | `number` | `120` | Timeout in seconds for building each presentation (10-600) | | `maxParallelBuilds` | `number` | `4` | Maximum parallel Slidev builds (capped at CPU count) | | `verbose` | `boolean` | `false` | Enable verbose logging for Slidev build output | | `assetExcludePatterns` | `string[]` | `[]` | Glob patterns for assets to exclude from copying | | `assetIncludePatterns` | `string[]` | `undefined` | Glob patterns for assets to include (whitelist mode) | | `assetCopyRecursive` | `boolean` | `true` | Whether to recursively copy asset subdirectories | ## All Frontmatter Options Configure individual presentations using frontmatter: | Option | Type | Description | | ------------- | --------------------- | ------------------------------------------------- | | `theme` | `string` | Theme to use (overrides plugin global theme) | | `title` | `string` | Presentation title | | `description` | `string` | Brief description for overview page | | `author` | `string` | Author name(s) | | `position` | `number` | Manual sort order (lower numbers appear first) | | `layout` | `string` | Layout for the slide (e.g., `cover`, `intro`) | | `assets` | `string \| string[]` | Explicit asset paths to copy (relative to .md file) | See [Slidev documentation](https://sli.dev/guide/syntax.html#frontmatter) for all available frontmatter options. ## Asset Handling The plugin automatically copies assets (images, videos, fonts, etc.) alongside your presentations during build. Assets referenced via relative paths in your slides will be available in the built output. ### Referencing Assets When referencing assets in your slides, **always use relative paths starting with `./`**: ```markdown ![Architecture diagram](./architecture.drawio.png) ![Logo](./assets/logo.svg) ![Architecture diagram](architecture.drawio.png) ``` :::warning[Important] Always prefix relative paths with `./` (e.g., `./image.png` instead of `image.png`). Slidev requires explicit relative paths to resolve assets correctly during the build process. ::: ### Automatic Mode (Default) By default, all assets in the slidev directory are copied automatically: ``` slidev/ ├── module-01.md ├── 01-architecture.drawio.png # Same directory asset ├── assets/ # Subdirectory │ └── 01-lifecycle.drawio.png └── images/ # Any subdirectory name works └── logo.svg ``` Reference them in your slides: ```markdown ![Architecture](./01-architecture.drawio.png) ![Lifecycle](./assets/01-lifecycle.drawio.png) ![Logo](./images/logo.svg) ``` ### Explicit Mode (Frontmatter) For precise control over which assets are copied, declare asset paths in your presentation's frontmatter: ```yaml --- theme: "@sp-days-framework/slidev-theme-sykehuspartner" title: My Presentation assets: - ./assets/module-01/ # Only this subdirectory - ./shared/ # Shared assets - ./logo.png # Individual file --- ``` When `assets` is defined in frontmatter, **only those paths are copied** for that presentation. This is useful for: - Large slidev directories with many assets - Presentations that only need specific files - Reducing build time by copying fewer files ### Plugin Configuration ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { // Exclude large source files from copying assetExcludePatterns: [ "*.psd", // Photoshop files "*.ai", // Illustrator files "drafts/**", // Draft assets folder ], // Or use whitelist mode - only copy these types assetIncludePatterns: [ "*.png", "*.jpg", "*.svg", "*.gif", "*.webp", ], // Disable recursive copying (only same directory) assetCopyRecursive: false, }, ], ], }; ``` ### Built-in Exclusions These patterns are always excluded regardless of configuration: - `node_modules/**` - Dependencies - `.git/**` - Git data - `*.md` - Other markdown files - `.DS_Store`, `Thumbs.db` - OS metadata - `_category_.yml/yaml/json` - Docusaurus category files ## Multiple Plugin Instances Run multiple instances with different configurations: ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { id: "workshops", path: "./slidev/workshops", routeBasePath: "/workshops", pageTitle: "Workshop Presentations", }, ], [ "@sp-days-framework/docusaurus-plugin-slidev", { id: "training", path: "./slidev/training", routeBasePath: "/training", pageTitle: "Training Materials", }, ], ], }; ``` :::note With multiple instances, the URL paths are derived from each `path`: - `./slidev/workshops` → presentations served at `/workshops/` - `./slidev/training` → presentations served at `/training/` ::: This allows you to organize different types of presentations separately. ## Global Theme Configuration Set a default theme for all presentations: ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { theme: "@sp-days-framework/slidev-theme-sykehuspartner", }, ], ], }; ``` Individual presentations can override this by specifying a theme in their frontmatter. ## Custom Overview Page Customize the presentation overview page appearance: ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { routeBasePath: "/presentations", pageTitle: "Our Presentations", pageTagline: "Explore our collection of learning materials", }, ], ], }; ``` ## Parallel Builds By default, presentations are built in parallel to significantly reduce build time. The plugin uses a worker pool pattern that dynamically allocates builds as slots become available. ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { maxParallelBuilds: 4, // Default: 4 (capped at CPU count) }, ], ], }; ``` :::tip[Resource-constrained environments] For CI/CD runners with limited resources, you can reduce parallel builds: ```js maxParallelBuilds: 2; // Lower concurrency for limited resources ``` Set to `1` for sequential builds (legacy behavior). ::: ## Build Timeout Configuration For large presentations, increase the build timeout: ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { buildTimeout: 120, // 2 minutes per presentation verbose: true, // Enable verbose logging }, ], ], }; ``` ## PDF Download Support Enable PDF download functionality for presentations: ```js title="docusaurus.config.js" module.exports = { plugins: [ [ "@sp-days-framework/docusaurus-plugin-slidev", { download: true, }, ], ], }; ``` :::warning[Playwright Chromium Required] PDF download requires `playwright-chromium` to be installed: ```bash npm install -D playwright-chromium ``` This adds approximately **300MB** to your dependencies. Only enable this feature if you need PDF exports. ::: ## Custom Sort Order ### Using Filename Convention By default, presentations are sorted by filename using natural sorting. This means files like `module-01.md`, `module-02.md`, ..., `module-10.md` will sort correctly (not as `01, 10, 02, 03...`). ### Using Position Frontmatter For manual control over sort order, use the `position` frontmatter field: ```markdown title="slidev/introduction.md" --- title: Welcome Introduction position: 1 --- # Welcome! ``` ```markdown title="slidev/advanced-topics.md" --- title: Advanced Topics position: 2.5 --- # Advanced Topics ``` **Sort priority:** 1. `position` (if specified) - lower numbers appear first 2. `sourcePath` - natural filename sorting 3. `title` - alphabetical fallback