@mdream/vite 0.7.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Harlan Wilton
+
+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,207 @@
+# @mdream/vite
+
+Vite plugin for HTML to Markdown conversion with on-demand generation support.
+
+## Features
+
+- **🚀 On-Demand Generation**: Access any HTML page as `.md` for instant markdown conversion
+- **⚡ Multi-Environment**: Works in development, preview, and production
+- **📦 Build Integration**: Generate static markdown files during build
+- **💾 Smart Caching**: Intelligent caching for optimal performance
+- **🎯 URL Pattern Matching**: Simple `.md` suffix for any HTML route
+- **🔧 Configurable**: Full control over processing and output
+
+## Installation
+
+```bash
+npm install @mdream/vite mdream
+# or
+pnpm add @mdream/vite mdream
+# or
+yarn add @mdream/vite mdream
+```
+
+## Usage
+
+Add the plugin to your `vite.config.js`:
+
+```javascript
+import { viteHtmlToMarkdownPlugin } from '@mdream/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    viteHtmlToMarkdownPlugin({
+      // Optional configuration
+      include: ['**/*.html'],
+      exclude: ['**/node_modules/**'],
+      outputDir: 'markdown',
+      cacheEnabled: true,
+      mdreamOptions: {
+        // mdream configuration options
+        plugins: []
+      }
+    })
+  ]
+})
+```
+
+## URL Pattern
+
+The plugin enables accessing any HTML path with a `.md` extension:
+
+- `/about` → `/about.md` (converts on-demand)
+- `/docs/guide.html` → `/docs/guide.md`
+- `/blog/post` → `/blog/post.md`
+
+## Configuration Options
+
+```typescript
+interface ViteHtmlToMarkdownOptions {
+  /**
+   * Glob patterns to include HTML files for processing
+   * @default ['**/*.html']
+   */
+  include?: string[]
+
+  /**
+   * Glob patterns to exclude from processing
+   * @default ['**/node_modules/**']
+   */
+  exclude?: string[]
+
+  /**
+   * Output directory for generated markdown files
+   * @default 'markdown'
+   */
+  outputDir?: string
+
+  /**
+   * Enable in-memory caching for development
+   * @default true
+   */
+  cacheEnabled?: boolean
+
+  /**
+   * Options to pass to mdream's htmlToMarkdown function
+   */
+  mdreamOptions?: HtmlToMarkdownOptions
+
+  /**
+   * Whether to preserve directory structure in output
+   * @default true
+   */
+  preserveStructure?: boolean
+
+  /**
+   * Custom cache TTL in milliseconds for production
+   * @default 3600000 (1 hour)
+   */
+  cacheTTL?: number
+
+  /**
+   * Whether to log conversion activities
+   * @default false
+   */
+  verbose?: boolean
+}
+```
+
+## How It Works
+
+### Development (`vite dev`)
+- **Middleware**: Intercepts `.md` requests via `configureServer`
+- **Transform Pipeline**: Uses Vite's transform system for HTML content
+- **Fallbacks**: Tries multiple path variations including SPA fallback
+- **Caching**: Memory cache with no-cache headers
+
+### Build Time (`vite build`)
+- **Bundle Processing**: Processes HTML files via `generateBundle` hook
+- **Static Generation**: Creates `.md` files alongside HTML output
+- **Pattern Matching**: Respects include/exclude patterns
+
+### Preview (`vite preview`)
+- **File System**: Reads from build output directory
+- **Caching**: Aggressive caching with TTL
+- **Multiple Paths**: Tries various file locations
+
+## Examples
+
+### Basic Setup
+
+```javascript
+import { viteHtmlToMarkdownPlugin } from '@mdream/vite'
+
+export default defineConfig({
+  plugins: [
+    viteHtmlToMarkdownPlugin()
+  ]
+})
+```
+
+### Advanced Configuration
+
+```javascript
+import { viteHtmlToMarkdownPlugin } from '@mdream/vite'
+
+export default defineConfig({
+  plugins: [
+    viteHtmlToMarkdownPlugin({
+      include: ['pages/**/*.html', 'docs/**/*.html'],
+      exclude: ['**/admin/**', '**/private/**'],
+      outputDir: 'public/markdown',
+      verbose: true,
+      mdreamOptions: {
+        plugins: [
+          // Custom mdream plugins
+        ]
+      }
+    })
+  ]
+})
+```
+
+### With Custom mdream Options
+
+```javascript
+import { viteHtmlToMarkdownPlugin } from '@mdream/vite'
+import { readabilityPlugin } from 'mdream/plugins'
+
+export default defineConfig({
+  plugins: [
+    viteHtmlToMarkdownPlugin({
+      mdreamOptions: {
+        plugins: [
+          readabilityPlugin({
+            minScore: 0.7
+          })
+        ]
+      }
+    })
+  ]
+})
+```
+
+## Integration with SSR
+
+For production SSR applications, you can extend your Express server:
+
+```javascript
+import express from 'express'
+import { createServer as createViteServer } from 'vite'
+
+const app = express()
+
+// In production, handle .md requests
+app.use(async (req, res, next) => {
+  if (req.path.endsWith('.md')) {
+    // Your custom SSR markdown handling
+    // The plugin provides the foundation
+  }
+  next()
+})
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,61 @@
+import { HTMLToMarkdownOptions } from "mdream";
+import { Plugin } from "vite";
+
+//#region src/types.d.ts
+interface ViteHtmlToMarkdownOptions {
+  /**
+   * Glob patterns to include HTML files for processing
+   * @default ['**\/*.html']
+   */
+  include?: string[];
+  /**
+   * Glob patterns to exclude from processing
+   * @default ['**\/node_modules\/**']
+   */
+  exclude?: string[];
+  /**
+   * Output directory for generated markdown files
+   * @default '' (same directory as HTML files)
+   */
+  outputDir?: string;
+  /**
+   * Enable in-memory caching for development
+   * @default true
+   */
+  cacheEnabled?: boolean;
+  /**
+   * Options to pass to mdream's htmlToMarkdown function
+   */
+  mdreamOptions?: HTMLToMarkdownOptions;
+  /**
+   * Whether to preserve directory structure in output
+   * @default true
+   */
+  preserveStructure?: boolean;
+  /**
+   * Custom cache TTL in milliseconds for production
+   * @default 3600000 (1 hour)
+   */
+  cacheTTL?: number;
+  /**
+   * Whether to log conversion activities
+   * @default false
+   */
+  verbose?: boolean;
+}
+interface CacheEntry {
+  content: string;
+  timestamp: number;
+  ttl: number;
+}
+interface MarkdownConversionResult {
+  content: string;
+  cached: boolean;
+  source: 'dev' | 'preview' | 'build';
+}
+type ViteHtmlToMarkdownPlugin = (options?: ViteHtmlToMarkdownOptions) => Plugin;
+//#endregion
+//#region src/plugin.d.ts
+declare function viteHtmlToMarkdownPlugin(userOptions?: ViteHtmlToMarkdownOptions): Plugin;
+//#endregion
+export { CacheEntry, MarkdownConversionResult, ViteHtmlToMarkdownOptions, ViteHtmlToMarkdownPlugin, viteHtmlToMarkdownPlugin as default, viteHtmlToMarkdownPlugin };

package/dist/index.mjs

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { htmlToMarkdown } from "mdream";
+
+//#region src/plugin.ts
+const DEFAULT_OPTIONS = {
+	include: ["**/*.html"],
+	exclude: ["**/node_modules/**"],
+	outputDir: "",
+	cacheEnabled: true,
+	mdreamOptions: {},
+	preserveStructure: true,
+	cacheTTL: 36e5,
+	verbose: true
+};
+function viteHtmlToMarkdownPlugin(userOptions = {}) {
+	const options = {
+		...DEFAULT_OPTIONS,
+		...userOptions
+	};
+	const markdownCache = new Map();
+	function log(message) {
+		if (options.verbose) console.log(`[vite-html-to-markdown] ${message}`);
+	}
+	function isValidCache(entry) {
+		return Date.now() - entry.timestamp < entry.ttl;
+	}
+	function getCachedMarkdown(key) {
+		if (!options.cacheEnabled) return null;
+		const entry = markdownCache.get(key);
+		if (entry && isValidCache(entry)) return entry.content;
+		if (entry) markdownCache.delete(key);
+		return null;
+	}
+	function setCachedMarkdown(key, content, ttl = options.cacheTTL) {
+		if (!options.cacheEnabled) return;
+		markdownCache.set(key, {
+			content,
+			timestamp: Date.now(),
+			ttl
+		});
+	}
+	async function convertHtmlToMarkdown(htmlContent, source) {
+		try {
+			const markdownContent = htmlToMarkdown(htmlContent, options.mdreamOptions);
+			log(`Converted ${source} to markdown (${markdownContent.length} chars)`);
+			return markdownContent;
+		} catch (error) {
+			throw new Error(`Failed to convert HTML to markdown: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	async function handleMarkdownRequest(url, server = null, outDir) {
+		let basePath = url.slice(0, -3);
+		if (basePath === "/index") basePath = "/";
+		const source = server ? "dev" : outDir ? "preview" : "build";
+		const cacheKey = `${source}:${basePath}`;
+		const cached = getCachedMarkdown(cacheKey);
+		if (cached) {
+			log(`Cache hit for ${url}`);
+			return {
+				content: cached,
+				cached: true,
+				source
+			};
+		}
+		let htmlContent = null;
+		if (server) {
+			const possiblePaths = [
+				basePath.endsWith(".html") ? basePath : `${basePath}.html`,
+				basePath,
+				"/index.html"
+			];
+			for (const htmlPath of possiblePaths) try {
+				const result = await server.transformRequest(htmlPath);
+				if (result?.code) {
+					htmlContent = result.code;
+					log(`Found HTML content for ${htmlPath}`);
+					break;
+				}
+			} catch {
+				continue;
+			}
+		} else if (outDir) {
+			const possiblePaths = [
+				path.join(outDir, `${basePath}.html`),
+				path.join(outDir, basePath, "index.html"),
+				path.join(outDir, "index.html")
+			];
+			for (const htmlPath of possiblePaths) if (fs.existsSync(htmlPath)) {
+				htmlContent = fs.readFileSync(htmlPath, "utf-8");
+				log(`Read HTML file from ${htmlPath}`);
+				break;
+			}
+		}
+		if (!htmlContent) throw new Error(`No HTML content found for ${url}`);
+		const markdownContent = await convertHtmlToMarkdown(htmlContent, url);
+		setCachedMarkdown(cacheKey, markdownContent);
+		return {
+			content: markdownContent,
+			cached: false,
+			source
+		};
+	}
+	function matchesPattern(fileName, patterns) {
+		return patterns.some((pattern) => {
+			const regexPattern = pattern.replace(/\./g, "\\.").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\?/g, ".");
+			const regex = new RegExp(`^${regexPattern}$`);
+			return regex.test(fileName);
+		});
+	}
+	return {
+		name: "vite-html-to-markdown",
+		configureServer(server) {
+			server.middlewares.use(async (req, res, next) => {
+				if (!req.url?.endsWith(".md")) return next();
+				try {
+					const result = await handleMarkdownRequest(req.url, server);
+					res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+					res.setHeader("Cache-Control", "no-cache");
+					res.setHeader("X-Markdown-Source", result.source);
+					res.setHeader("X-Markdown-Cached", result.cached.toString());
+					res.end(result.content);
+					log(`Served ${req.url} from ${result.source} (cached: ${result.cached})`);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					log(`Error serving ${req.url}: ${message}`);
+					res.statusCode = 404;
+					res.end(`HTML content not found for ${req.url}`);
+				}
+			});
+		},
+		generateBundle(outputOptions, bundle) {
+			const htmlFiles = Object.entries(bundle).filter(([fileName, file]) => {
+				return fileName.endsWith(".html") && file.type === "asset" && matchesPattern(fileName, options.include) && !matchesPattern(fileName, options.exclude);
+			});
+			log(`Processing ${htmlFiles.length} HTML files for markdown generation`);
+			for (const [fileName, htmlFile] of htmlFiles) try {
+				if (htmlFile.type !== "asset" || !("source" in htmlFile)) continue;
+				const htmlContent = htmlFile.source;
+				const markdownContent = htmlToMarkdown(htmlContent, options.mdreamOptions);
+				const markdownFileName = fileName.replace(".html", ".md");
+				const outputPath = options.preserveStructure ? `${options.outputDir}/${markdownFileName}` : `${options.outputDir}/${path.basename(markdownFileName)}`;
+				this.emitFile({
+					type: "asset",
+					fileName: outputPath,
+					source: markdownContent
+				});
+				log(`Generated markdown: ${outputPath}`);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(`[vite-html-to-markdown] Failed to convert ${fileName}: ${message}`);
+			}
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use(async (req, res, next) => {
+				if (!req.url?.endsWith(".md")) return next();
+				try {
+					const outDir = server.config.build?.outDir || "dist";
+					const result = await handleMarkdownRequest(req.url, null, outDir);
+					res.setHeader("Content-Type", "text/markdown; charset=utf-8");
+					res.setHeader("Cache-Control", "public, max-age=3600");
+					res.setHeader("X-Markdown-Source", result.source);
+					res.setHeader("X-Markdown-Cached", result.cached.toString());
+					res.end(result.content);
+					log(`Served ${req.url} from ${result.source} (cached: ${result.cached})`);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					log(`Error in preview server for ${req.url}: ${message}`);
+					res.statusCode = 404;
+					res.end(`HTML content not found for ${req.url}`);
+				}
+			});
+		}
+	};
+}
+
+//#endregion
+//#region src/index.ts
+var src_default = viteHtmlToMarkdownPlugin;
+
+//#endregion
+export { src_default as default, viteHtmlToMarkdownPlugin };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mdream/vite",
+  "type": "module",
+  "version": "0.7.0",
+  "description": "Vite plugin for HTML to Markdown conversion with on-demand generation",
+  "author": {
+    "name": "Harlan Wilton",
+    "email": "harlan@harlanzw.com",
+    "url": "https://harlanzw.com/"
+  },
+  "license": "MIT",
+  "keywords": [
+    "vite",
+    "plugin",
+    "html",
+    "markdown",
+    "converter",
+    "ssr",
+    "on-demand",
+    "llm"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0"
+  },
+  "dependencies": {
+    "mdream": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vite": "^6.0.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "typecheck": "tsc --noEmit",
+    "dev:prepare": "obuild --stub",
+    "test": "vitest test",
+    "test:attw": "attw --pack"
+  }
+}