@sp-days-framework/docusaurus-plugin-slidev 1.1.0-beta2 → 1.1.0-beta3

package/docs/advanced-configuration.mdx

@@ -12,18 +12,20 @@ import TabItem from "@theme/TabItem";
 
 ## All Plugin Options
 
-| 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                                  |
-| `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                     |
+| 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                         |
+
+
 
 ## All Frontmatter Options
 
@@ -35,6 +37,7 @@ Configure individual presentations using frontmatter:
 | `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`)  |
 
 See [Slidev documentation](https://sli.dev/guide/syntax.html#frontmatter) for all available frontmatter options.
@@ -45,31 +48,36 @@ Run multiple instances with different configurations:
 
 ```js title="docusaurus.config.js"
 module.exports = {
-  staticDirectories: ["static"],
-  
   plugins: [
     [
       "@sp-days-framework/docusaurus-plugin-slidev",
       {
         id: "workshops",
-        sourceDir: "./slidev/workshops",
-        overviewPath: "/workshops/slides",
-        overviewTitle: "Workshop Presentations",
+        path: "./slidev/workshops",
+        routeBasePath: "/workshops",
+        pageTitle: "Workshop Presentations",
       },
     ],
     [
       "@sp-days-framework/docusaurus-plugin-slidev",
       {
         id: "training",
-        sourceDir: "./slidev/training",
-        overviewPath: "/training/slides",
-        overviewTitle: "Training Materials",
+        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
@@ -101,15 +109,42 @@ module.exports = {
     [
       "@sp-days-framework/docusaurus-plugin-slidev",
       {
-        overviewPath: "/presentations",
-        overviewTitle: "Our Presentations",
-        overviewTagline: "Explore our collection of learning materials",
+        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:
@@ -121,7 +156,7 @@ module.exports = {
       "@sp-days-framework/docusaurus-plugin-slidev",
       {
         buildTimeout: 120, // 2 minutes per presentation
-        verbose: true,     // Enable verbose logging
+        verbose: true, // Enable verbose logging
       },
     ],
   ],
@@ -144,3 +179,47 @@ module.exports = {
   ],
 };
 ```
+
+:::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

package/docs/changelog.mdx

@@ -19,6 +19,58 @@ All packages within `@sp-days-framework` use the same version number. In some ca
 
 ---
 
+## Version 1.1.0-beta3 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Bug fixes, improved build output, and new features including directory support for organizing presentations
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 12)</summary>
+
+### Bug Fixes
+
+- **Grid View Sorting** - Fixed sorting to use natural sort on `sourcePath` instead of `title`, correctly handling numeric sequences like `module-01`, `module-02`, ..., `module-10`
+- **Strict Theme Validation** - Changed from warning to error when theme is not installed, preventing build hangs
+- **Build Output Filtering** - Suppressed verbose Vite/Slidev output including chunk manifests, transformation progress, and outDir warnings
+- **Build Timeout** - Increased default timeout from 60s to 120s for large presentations
+
+### New Features
+
+- **Hidden Build Output** - Presentations are now built to a hidden `.docusaurus` cache directory instead of `static/`, keeping the user's workspace clean. Build artifacts are automatically copied to the final output during the Docusaurus build process
+- **Directory Support** - Organize presentations into directories with `_category_.yml`/`_category_.json` metadata files for better navigation and grouping. See [Slide Directory](./slide-directory.mdx) for details
+- **Parallel Builds** - Added `maxParallelBuilds` option (default: 4) to build multiple presentations simultaneously, significantly reducing total build time
+- **Position Frontmatter** - Added `position` field to manually control sort order (lower numbers first, supports decimals)
+- **SlidevLink Component** - New embeddable component for displaying slide previews in MDX documentation
+- **Renamed Options** - Updated option names to better match Docusaurus conventions
+
+### Breaking Changes
+
+- **Removed `outputDir` option** - The URL path is now automatically derived from `path`. For example, `path: './slidev'` serves presentations at `/slidev/`. This simplifies configuration and eliminates the need for manual `.gitignore` entries for build artifacts
+
+### Deprecated Options
+
+The following options have been renamed and will be removed in a future version:
+
+| Deprecated Option   | New Option       | Notes                                         |
+| ------------------- | ---------------- | --------------------------------------------- |
+| `sourceDir`         | `path`           | Matches Docusaurus plugin conventions         |
+| `overviewPath`      | `routeBasePath`  | Matches Docusaurus `docs` plugin naming       |
+| `overviewTitle`     | `pageTitle`      | More concise naming                           |
+| `overviewTagline`   | `pageTagline`    | More concise naming                           |
+
+The old options still work but will log a deprecation warning. Update your configuration to use the new names.
+
+### Improvements
+
+- **Cleaner Workspace** - No more `static/slides/` directory cluttering your project
+- **Faster Builds** - Parallel build support reduces build time by up to 4x on multi-core machines
+- **Cleaner Build Output** - Build now shows only completion messages with timing (no Vite noise)
+- **Natural Sorting** - File paths with numbers now sort correctly using `Intl.Collator`
+- **Better Error Messages** - Theme not found errors now include installation command
+
+</details>
+
+---
+
 ## Version 1.1.0-beta2 ![beta](https://img.shields.io/badge/release-beta-yellow)
 
 Documentation improvements and visual refinements

package/docs/install.mdx

@@ -48,18 +48,12 @@ Install Slidev dependencies:
 
 Add the plugin to your `docusaurus.config.js`:
 
-```js title="docusaurus.config.js" {2,4}
+```js title="docusaurus.config.js"
 module.exports = {
-  staticDirectories: ["static"],
-  
   plugins: ["@sp-days-framework/docusaurus-plugin-slidev"],
 };
 ```
 
-:::note
-The `static` directory is required for serving built presentations.
-:::
-
 **Optional:** Add the `slidev` script for live preview during development:
 
 ```json title="package.json" {4}
@@ -79,11 +73,27 @@ The plugin works with default settings:
 
 ```js title="docusaurus.config.js"
 module.exports = {
-  staticDirectories: ["static"],
   plugins: ["@sp-days-framework/docusaurus-plugin-slidev"],
 };
 ```
 
+### Adding to Navbar
+
+To add the Slidev overview page to your navbar, update your `docusaurus.config.js`:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  themeConfig: {
+    navbar: {
+      items: [
+        // ... other items
+        { to: "/slidev", label: "Slides", position: "left" },
+      ],
+    },
+  },
+};
+```
+
 ### Plugin Options
 
 Customize the plugin behavior:
@@ -94,10 +104,9 @@ module.exports = {
     [
       "@sp-days-framework/docusaurus-plugin-slidev",
       {
-        sourceDir: "./slidev",
-        outputDir: "slides",
+        path: "./slidev",
         theme: "@sp-days-framework/slidev-theme-sykehuspartner",
-        overviewPath: "/presentations",
+        routeBasePath: "/slidev",
       },
     ],
   ],
@@ -106,13 +115,13 @@ module.exports = {
 
 Common options:
 
-| 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                        |
-| `overviewPath`    | `string`  | `'/slidev'`                           | URL path for the auto-generated overview page                      |
-| `overviewTitle`   | `string`  | `'Slidev Presentations'`              | Title for the overview page                                        |
+| Option              | Type      | Default                               | Description                                                         |
+| ------------------- | --------- | ------------------------------------- | ------------------------------------------------------------------- |
+| `path`              | `string`  | `'./slidev'`                          | Directory for Slidev files (also determines URL path)               |
+| `theme`             | `string`  | `undefined`                           | Global theme override for all presentations                         |
+| `routeBasePath`     | `string`  | `'/slidev'`                           | URL path for the auto-generated overview page                       |
+| `pageTitle`         | `string`  | `'Slidev Presentations'`              | Title for the overview page                                         |
+| `maxParallelBuilds` | `number`  | `4`                                   | Maximum parallel Slidev builds (capped at CPU count)                |
 
 See [Advanced Configuration](./advanced-configuration.mdx) for all options.
 

package/docs/slide-directory.mdx

@@ -0,0 +1,184 @@
+---
+sidebar_position: 2.2
+sidebar_label: "Slide Directory"
+sidebar_custom_props:
+  section: "Features"
+  section_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Slide Directory
+
+Organize your presentations into directories for better navigation and grouping. This is especially useful when you have many presentations that belong to different categories, modules, or topics.
+
+## Directory Structure
+
+Create subdirectories within your `path` directory to group presentations:
+
+```
+slidev/
+├── introduction.md           # Root-level presentation
+├── getting-started.md        # Root-level presentation
+├── advanced/                  # Category directory
+│   ├── _category_.yml         # Category metadata (optional)
+│   ├── networking.md
+│   └── security.md
+└── workshops/                 # Another category
+    ├── _category_.yml
+    ├── hands-on-docker.md
+    └── kubernetes-basics.md
+```
+
+## Category Metadata
+
+Configure category appearance using `_category_.yml` or `_category_.json`:
+
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+    ```yaml title="slidev/advanced/_category_.yml"
+    label: "Advanced Topics"
+    description: "Deep dives into complex subjects"
+    position: 2
+    ```
+  </TabItem>
+  <TabItem value="json" label="JSON">
+    ```json title="slidev/advanced/_category_.json"
+    {
+      "label": "Advanced Topics",
+      "description": "Deep dives into complex subjects",
+      "position": 2
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+| Field         | Type     | Default        | Description                                      |
+| ------------- | -------- | -------------- | ------------------------------------------------ |
+| `label`       | `string` | Directory name | Display name shown in overview                   |
+| `description` | `string` | `undefined`    | Brief description shown in category card/listing |
+| `position`    | `number` | `99`           | Sort order (lower numbers appear first)          |
+
+:::tip[No metadata file?]
+If you don't create a `_category_.yml` file, the directory name will be used as the label (converted to title case: `my-category` → `My Category`).
+:::
+
+## Overview Navigation
+
+The overview page adapts to show directory content:
+
+### Root Level View
+
+Shows:
+
+- All root-level presentations
+- Category folders as clickable cards
+
+### Category View
+
+When clicking a category folder:
+
+- Shows presentations within that category
+- Displays a back button to return to parent
+- Category label and description replace the default title
+
+## URL Structure
+
+Presentations in directories have paths that reflect their location:
+
+| File Path                       | Presentation URL               |
+| ------------------------------- | ------------------------------ |
+| `slidev/intro.md`               | `/slides/intro/`               |
+| `slidev/advanced/networking.md` | `/slides/advanced/networking/` |
+| `slidev/workshops/docker.md`    | `/slides/workshops/docker/`    |
+
+Category overview pages are accessible at:
+
+| Category Path | Overview URL        |
+| ------------- | ------------------- |
+| Root          | `/slidev`           |
+| `advanced`    | `/slidev/advanced`  |
+| `workshops`   | `/slidev/workshops` |
+
+## Grid vs List View
+
+Both views support directory navigation:
+
+### Grid View
+
+- Categories appear as folder cards with an icon
+- Shows category label, description, and presentation count
+- Click to navigate into the category
+
+### List View
+
+- Categories appear as rows with folder icon prefix
+- Compact display with label, description, and count
+- Same click-to-navigate behavior
+
+## Nested Directories
+
+You can nest directories multiple levels deep:
+
+```
+slidev/
+└── training/
+    ├── _category_.yml
+    ├── beginner/
+    │   ├── _category_.yml
+    │   └── basics.md
+    └── advanced/
+        ├── _category_.yml
+        └── expert-tips.md
+```
+
+The back button always navigates to the parent level, allowing easy traversal through nested structures.
+
+## Sorting Within Categories
+
+Presentations within a category follow the same sorting rules:
+
+1. `position` frontmatter (if specified)
+2. `sourcePath` (natural filename sorting)
+3. `title` (alphabetical fallback)
+
+Categories themselves are sorted by their `position` field, then by label.
+
+## Example Configuration
+
+```yaml title="slidev/modules/_category_.yml"
+label: "Course Modules"
+description: "Step-by-step learning path for the complete course"
+position: 1
+```
+
+```markdown title="slidev/modules/module-01-intro.md"
+---
+title: "Module 1: Introduction"
+description: "Getting started with the fundamentals"
+position: 1
+---
+
+# Introduction
+
+Welcome to Module 1!
+```
+
+```markdown title="slidev/modules/module-02-basics.md"
+---
+title: "Module 2: Core Concepts"
+description: "Understanding the building blocks"
+position: 2
+---
+
+# Core Concepts
+
+Let's explore the basics...
+```
+
+## Backward Compatibility
+
+- **Flat structures still work** - If you don't use directories, everything works as before
+- **Mixed structures supported** - You can have both root-level files and directories
+- **No configuration required** - Directory support is automatic

package/docs/slidev-link.mdx

@@ -0,0 +1,40 @@
+---
+sidebar_position: 2.1
+sidebar_label: "Slidev Link"
+sidebar_custom_props:
+  section: "Features"
+  section_position: 2
+---
+
+import SlidevLink from "@theme/SlidevLink";
+
+# Slidev Link Component
+
+Embed slide previews directly in your MDX documentation:
+
+<SlidevLink link="/slidev/creating-your-first-slidev" />
+
+## Example Usage
+
+```mdx
+import SlidevLink from "@theme/SlidevLink";
+
+# Module 1: Introduction
+
+Before starting this module, review the presentation:
+
+<SlidevLink link="/slidev/module-01" />
+```
+
+### Props
+
+| Prop       | Type     | Default     | Description                         |
+| ---------- | -------- | ----------- | ----------------------------------- |
+| `link`     | `string` | _required_  | URL path to the presentation        |
+| `width`    | `string` | `'550px'`   | Card width                          |
+| `pluginId` | `string` | `'default'` | Plugin ID for multi-instance setups |
+
+
+## Error Handling
+
+If the presentation URL doesn't exist, the component displays an error state with the invalid path, making it easy to identify broken links during development.

package/lib/plugin/builder.d.ts

@@ -4,17 +4,23 @@
 import type { PresentationMetadata, PluginOptions, BuildResult } from "../types";
 /**
  * Builds a single Slidev presentation with real-time output streaming
+ * Uses isolated build directories to prevent race conditions during parallel builds
  */
 /**
  * Builds a single Slidev presentation with real-time output streaming
+ * Uses isolated build directories to prevent race conditions during parallel builds
  */
 export declare function buildPresentation(presentation: PresentationMetadata, options: PluginOptions, context: {
     siteDir: string;
     baseUrl: string;
-}): Promise<BuildResult>;
+}, cacheDir?: string): Promise<BuildResult>;
 /**
- * Builds all presentations sequentially
- * Returns array of build results
+ * Builds all presentations with parallel execution using a worker pool pattern.
+ * Uses dynamic slot allocation - as soon as a build completes, a new one starts.
+ * This is more efficient than batch processing when build times vary.
+ *
+ * Each presentation is built in an isolated directory within .docusaurus
+ * to prevent race conditions from Slidev creating index.html in the source directory.
  */
 export declare function buildAllPresentations(presentations: PresentationMetadata[], options: PluginOptions, context: {
     siteDir: string;

package/lib/plugin/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/plugin/builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,WAAW,EACZ,MAAM,UAAU,CAAC;AAoHlB;;GAEG;AACH;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,oBAAoB,EAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,WAAW,CAAC,CAwPtB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,oBAAoB,EAAE,EACrC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,WAAW,EAAE,CAAC,CA8CxB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAU7D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,oBAAoB,EAClC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAuGV"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/plugin/builder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,WAAW,EACZ,MAAM,UAAU,CAAC;AAqIlB;;;GAGG;AACH;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,oBAAoB,EAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC7C,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CA2QtB;AAeD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,oBAAoB,EAAE,EACrC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,WAAW,EAAE,CAAC,CA2FxB;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC,CAU7D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,oBAAoB,EAClC,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAuGV"}