slidev-prerender 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuma Ichimura
+
+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,184 @@
+<h1 align="center">Slidev Prerender</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/slidev-prerender"><img src="https://img.shields.io/npm/v/slidev-prerender.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/slidev-prerender"><img src="https://img.shields.io/npm/dm/slidev-prerender.svg" alt="npm downloads"></a>
+  <a href="https://github.com/slidev-prerender/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/slidev-prerender.svg" alt="license"></a>
+</p>
+
+<p align="center">
+  Pre-render your <a href="https://sli.dev">Slidev</a> presentations as Multi-Page Applications (MPA) with enhanced SEO and metadata support.
+</p>
+
+## ✨ Features
+
+- 🎯 **MPA Generation** - Convert your Slidev presentation into multiple HTML files (one per slide)
+- 🔍 **SEO Optimization** - Customize meta tags, Open Graph, and Twitter Card for each slide
+- ⚡ **Static Deployment** - Deploy to any static hosting service (Netlify, Vercel, GitHub Pages, etc.)
+- 🎨 **Custom Metadata** - Set unique titles and SEO metadata for individual slides
+
+## 📦 Installation
+
+```bash
+# npm
+npm install -D slidev-prerender
+
+# pnpm
+pnpm add -D slidev-prerender
+
+# yarn
+yarn add -D slidev-prerender
+```
+
+## 🚀 Quick Start
+
+### 1. Build your Slidev presentation
+
+First, build your Slidev presentation:
+
+```bash
+npx slidev build
+```
+
+This will generate a `dist` folder with your Slidev build output.
+
+### 2. Run slidev-prerender
+
+```bash
+npx slidev-prerender
+```
+
+By default, this will:
+
+- Read from `./dist` (your Slidev build output)
+- Generate pre-rendered pages in `./dist-prerender`
+- Create one HTML file per slide (1.html, 2.html, 3.html, etc.)
+
+## ⚙️ Configuration
+
+Create a `slidev-prerender.config.ts` file in your project root:
+
+```typescript
+import { defineConfig } from "slidev-prerender";
+
+export default defineConfig({
+  // Directory where Slidev built files are located
+  slidevDist: "./dist",
+
+  // Output directory for pre-rendered pages
+  outDir: "./dist-prerender",
+
+  // Port to use for the local server during rendering (default: 3030)
+  port: 3030,
+
+  // Configuration for individual pages
+  pages: [
+    {
+      id: "1",
+      meta: {
+        fileName: "Introduction - My Presentation",
+        seoMeta: {
+          ogTitle: "Welcome to My Presentation",
+          ogDescription: "An introduction to the main topics",
+          ogImage: "https://example.com/slide1.png",
+          twitterCard: "summary_large_image",
+        },
+      },
+    },
+    {
+      id: "2",
+      meta: {
+        fileName: "Key Concepts",
+        seoMeta: {
+          ogTitle: "Understanding the Key Concepts",
+          ogDescription: "Deep dive into the core ideas",
+        },
+      },
+    },
+    // Add more pages as needed
+  ],
+});
+```
+
+### Configuration Options
+
+#### `UserConfig`
+
+| Option       | Type            | Default              | Description                                  |
+| ------------ | --------------- | -------------------- | -------------------------------------------- |
+| `slidevDist` | `string`        | `"./dist"`           | Path to your Slidev build output directory   |
+| `outDir`     | `string`        | `"./dist-prerender"` | Output directory for pre-rendered pages      |
+| `port`       | `number`        | `3030`               | Port for the local server during rendering   |
+| `pages`      | `PageConfig[]`  | `[]`                 | Configuration for individual slides          |
+
+#### `PageConfig`
+
+| Option | Type               | Description                                       |
+| ------ | ------------------ | ------------------------------------------------- |
+| `id`   | `string`           | Slide number or identifier (e.g., "1", "2", "3") |
+| `meta` | `BuildHeadOptions` | Metadata configuration for the slide              |
+
+#### `BuildHeadOptions`
+
+| Option     | Type      | Description                          |
+| ---------- | --------- | ------------------------------------ |
+| `title`    | `string`  | Page title (appears in browser tab)  |
+| `seoMeta`  | `SEOMeta` | SEO and social media metadata        |
+
+#### `SEOMeta`
+
+| Option                | Type     | Description                                       |
+| --------------------- | -------- | ------------------------------------------------- |
+| `ogTitle`             | `string` | Open Graph title                                  |
+| `ogDescription`       | `string` | Open Graph description                            |
+| `ogImage`             | `string` | Open Graph image URL                              |
+| `ogUrl`               | `string` | Open Graph URL                                    |
+| `twitterCard`         | `string` | Twitter Card type (e.g., "summary_large_image")  |
+| `twitterTitle`        | `string` | Twitter title                                     |
+| `twitterDescription`  | `string` | Twitter description                               |
+| `twitterImage`        | `string` | Twitter image URL                                 |
+
+## 🌐 Deployment
+
+Deploy the generated `dist-prerender` folder like any static site:
+
+1. Build and prerender:
+
+   ```bash
+   npx slidev build
+   npx slidev-prerender
+   ```
+
+2. Upload `dist-prerender` to your host (Netlify/Vercel static export, GitHub Pages, S3+CloudFront, etc.).
+3. Preview locally with any static server (e.g. `npx serve dist-prerender`).
+
+For more details on hosting options, see the [Slidev Hosting Guide](https://sli.dev/guide/hosting#hosting).
+
+## 🤔 Why Use This?
+
+When you share a Slidev presentation link on social media (Twitter, Facebook, Slack, etc.), the preview often shows generic information instead of details about the specific slide. This happens because Slidev presentations are Single Page Applications (SPAs), which makes it difficult for social platforms to extract slide-specific metadata. `slidev-prerender` solves this by generating separate HTML files for each slide with custom Open Graph and Twitter Card metadata, ensuring that every slide shows rich, compelling previews when shared.
+
+## 🛠️ How It Works
+
+1. Reads your Slidev build output
+2. Starts a local server with your presentation
+3. Uses Playwright to navigate to each slide
+4. Captures the rendered HTML and injects custom metadata
+5. Saves each slide as a separate HTML file
+6. Copies all assets (CSS, JS, images) to the output directory
+
+## 📄 License
+
+[MIT](LICENSE)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 💬 Support
+
+If you have any questions or issues, please [open an issue](https://github.com/slidev-prerender/issues) on GitHub.
+
+---
+
+Made with ❤️ for the [Slidev](https://sli.dev) community

package/bin/slidev-prerender.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict'
+import('../dist/run.mjs')

package/dist/index.d.mts

@@ -0,0 +1,31 @@
+import { SeoMeta } from "@slidev/types";
+import { ResolvableLink } from "unhead/types";
+
+//#region src/build/handle-head.d.ts
+type BuildHeadOptions = {
+  lang?: string;
+  title: string;
+  description?: string | null;
+  canonicalUrl?: string | null;
+  ogImage?: string | null;
+  twitterCard?: string | null;
+  favicon?: string | null;
+  webFonts?: ResolvableLink[];
+  seoMeta?: Partial<SeoMeta>;
+};
+//#endregion
+//#region src/config/loadConfig.d.ts
+type UserConfig = {
+  slidevDist?: string;
+  outDir?: string;
+  pages?: {
+    fileName: string;
+    meta?: BuildHeadOptions;
+  }[];
+  port?: number;
+};
+//#endregion
+//#region src/config/defineConfig.d.ts
+declare function defineConfig(config: UserConfig): UserConfig;
+//#endregion
+export { type UserConfig, defineConfig };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+//#region src/config/defineConfig.ts
+function defineConfig(config) {
+	return config;
+}
+
+//#endregion
+export { defineConfig };

package/dist/run.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/run.mjs

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path, { resolve } from "node:path";
+import { chromium } from "@playwright/test";
+import http from "node:http";
+import sirv from "sirv";
+import { escapeHtml } from "markdown-it/lib/common/utils.mjs";
+import { createHead, transformHtmlTemplate } from "unhead/server";
+import { parseHtmlForUnheadExtraction } from "unhead/parser";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+
+//#region src/build/handle-dist.ts
+async function removeDist(outDir) {
+	await fs.rm(outDir, {
+		recursive: true,
+		force: true
+	});
+	await fs.mkdir(outDir, { recursive: true });
+}
+async function serveDist(distPath, port) {
+	const serve = sirv(distPath, {
+		etag: true,
+		single: true
+	});
+	const server = http.createServer((req, res) => serve(req, res));
+	await new Promise((resolve$1, reject) => {
+		server.once("error", reject);
+		server.listen(port, resolve$1);
+	});
+	return {
+		origin: `http://localhost:${port}`,
+		close: () => new Promise((resolve$1) => server.close(() => resolve$1()))
+	};
+}
+async function getPageHtml(page, pageUrl) {
+	await page.goto(pageUrl, { waitUntil: "networkidle" });
+	return "<!doctype html>\n" + await page.content();
+}
+
+//#endregion
+//#region src/utils/file.ts
+async function copyDir(src, dst) {
+	await fs.mkdir(dst, { recursive: true });
+	for (const e of await fs.readdir(src, { withFileTypes: true })) {
+		const s = path.join(src, e.name);
+		const d = path.join(dst, e.name);
+		e.isDirectory() ? await copyDir(s, d) : await fs.copyFile(s, d);
+	}
+}
+
+//#endregion
+//#region src/build/handle-head.ts
+function toAttrValue(unsafe) {
+	return JSON.stringify(escapeHtml(String(unsafe)));
+}
+async function applyHead(html, opt) {
+	const extracted = parseHtmlForUnheadExtraction(html).input;
+	const description = opt.description ? toAttrValue(opt.description) : null;
+	return await transformHtmlTemplate(createHead({ init: [extracted, {
+		htmlAttrs: opt.lang ? { lang: opt.lang } : void 0,
+		title: opt.title,
+		link: [
+			opt.favicon ? {
+				rel: "icon",
+				href: opt.favicon
+			} : null,
+			...opt.webFonts ?? [],
+			opt.canonicalUrl ? {
+				rel: "canonical",
+				href: opt.canonicalUrl
+			} : null
+		].filter(Boolean),
+		meta: [
+			{
+				name: "description",
+				content: description
+			},
+			{
+				property: "og:title",
+				content: opt.seoMeta?.ogTitle || opt.title
+			},
+			{
+				property: "og:description",
+				content: opt.seoMeta?.ogDescription || description
+			},
+			{
+				property: "og:image",
+				content: opt.ogImage ?? opt.seoMeta?.ogImage
+			},
+			{
+				property: "og:url",
+				content: opt.seoMeta?.ogUrl || opt.canonicalUrl
+			},
+			{
+				name: "twitter:card",
+				content: opt.twitterCard ?? opt.seoMeta?.twitterCard
+			},
+			{
+				name: "twitter:title",
+				content: opt.seoMeta?.twitterTitle || opt.title
+			},
+			{
+				name: "twitter:description",
+				content: opt.seoMeta?.twitterDescription || description
+			},
+			{
+				name: "twitter:image",
+				content: (opt.seoMeta?.twitterImage || opt.ogImage) ?? opt.seoMeta?.ogImage
+			},
+			{
+				name: "twitter:url",
+				content: opt.seoMeta?.twitterUrl || opt.canonicalUrl
+			}
+		].filter((x) => x.content)
+	}] }), html);
+}
+
+//#endregion
+//#region src/config/loadConfig.ts
+const CONFIG_FILE_NAMES = [
+	"slidev-prerender.config.ts",
+	"slidev-prerender.config.mts",
+	"slidev-prerender.config.js",
+	"slidev-prerender.config.mjs"
+];
+async function loadConfig(cwd = process.cwd()) {
+	for (const fileName of CONFIG_FILE_NAMES) {
+		const configPath = resolve(cwd, fileName);
+		if (existsSync(configPath)) try {
+			const configModule = await import(pathToFileURL(configPath).href);
+			return configModule.default || configModule;
+		} catch (error) {
+			throw new Error(`Failed to load config from ${configPath}: ${error}`);
+		}
+	}
+	return {};
+}
+
+//#endregion
+//#region src/build/getConfig.ts
+const DEFAULT_CONFIG = {
+	slidevDist: "dist",
+	outDir: "dist-prerender",
+	pages: [],
+	port: 4173
+};
+async function getConfig() {
+	const config = await loadConfig();
+	return {
+		slidevDist: config.slidevDist ?? DEFAULT_CONFIG.slidevDist,
+		outDir: config.outDir ?? DEFAULT_CONFIG.outDir,
+		pages: config.pages ?? DEFAULT_CONFIG.pages,
+		port: config.port ?? DEFAULT_CONFIG.port
+	};
+}
+
+//#endregion
+//#region src/build/index.ts
+async function run() {
+	const { slidevDist, outDir, pages, port } = await getConfig();
+	try {
+		await fs.access(slidevDist);
+	} catch {
+		throw new Error(`Slidev dist directory not found: ${slidevDist}\nPlease run 'slidev build' first.`);
+	}
+	await removeDist(outDir);
+	const assetsPath = path.join(slidevDist, "assets");
+	try {
+		await fs.access(assetsPath);
+		await copyDir(assetsPath, path.join(outDir, "assets"));
+	} catch {
+		console.warn(`Assets directory not found: ${assetsPath}, skipping...`);
+	}
+	const { origin, close: serverClose } = await serveDist(slidevDist, port);
+	const browser = await chromium.launch();
+	const page = await browser.newPage();
+	try {
+		for (const n of pages) {
+			console.log(`[SSG] page ${n.fileName}`);
+			const html = await applyHead(await getPageHtml(page, `${origin}/${n.fileName}`), n.meta ?? { title: `ページ${n.fileName}` });
+			await fs.writeFile(path.join(outDir, `${n.fileName}.html`), html);
+		}
+	} finally {
+		await browser.close();
+		serverClose();
+	}
+	console.log("done");
+}
+
+//#endregion
+//#region src/run.ts
+await run();
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "slidev-prerender",
+  "type": "module",
+  "version": "0.0.1-alpha.0",
+  "description": "",
+  "author": "petaxa <soccer.i_y@icloud.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/petaxa/slidev-prerender/packages/core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petaxa/slidev-prerender.git"
+  },
+  "bugs": {
+    "url": "https://github.com/petaxa/slidev-prerender/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "slidev-prerender": "./bin/slidev-prerender.mjs"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "dependencies": {
+    "@playwright/test": "^1.57.0",
+    "markdown-it": "^14.1.0",
+    "unhead": "^2.1.1",
+    "sirv": "^3.0.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}