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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Helse Sør-Øst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,286 @@
+# @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";
+```

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Main entry point for @sp-days-framework/docusaurus-plugin-slidev
+ */
+export { default } from './plugin';
+export { validateOptions } from './plugin';
+export type * from './types';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,mBAAmB,SAAS,CAAC"}

package/lib/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Main entry point for @sp-days-framework/docusaurus-plugin-slidev
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = exports.default = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(plugin_1).default; } });
+var plugin_2 = require("./plugin");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return plugin_2.validateOptions; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;AAEH,mCAAmC;AAA1B,kHAAA,OAAO,OAAA;AAChB,mCAA2C;AAAlC,yGAAA,eAAe,OAAA"}

package/lib/plugin/builder.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Builder utility for compiling Slidev presentations
+ */
+import type { PresentationMetadata, PluginOptions, BuildResult } from "../types";
+/**
+ * Builds a single Slidev presentation with real-time output streaming
+ */
+/**
+ * Builds a single Slidev presentation with real-time output streaming
+ */
+export declare function buildPresentation(presentation: PresentationMetadata, options: PluginOptions, context: {
+    siteDir: string;
+    baseUrl: string;
+}): Promise<BuildResult>;
+/**
+ * Builds all presentations sequentially
+ * Returns array of build results
+ */
+export declare function buildAllPresentations(presentations: PresentationMetadata[], options: PluginOptions, context: {
+    siteDir: string;
+    baseUrl: string;
+}): Promise<BuildResult[]>;
+/**
+ * Checks if Slidev CLI is available
+ */
+export declare function checkSlidevInstalled(): Promise<boolean>;
+/**
+ * Diagnoses common issues with a presentation
+ */
+export declare function diagnosePresentationIssues(presentation: PresentationMetadata, siteDir?: string): string[];
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +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"}