scavold 0.2.0-rc.1

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+import type { App } from "vue";
+import type { Router } from "vitepress";
+
+/**
+ * Theme entry point: registers Scavold's i18n catalogue, makes every Scavold
+ * component globally available, and installs the runtime redirect handling.
+ * Call it from the site theme's own `enhanceApp()`.
+ */
+export function enhanceApp( context: { app: App; router: Router } ): Promise<void>;

package/lib/index.js

@@ -0,0 +1,60 @@
+import { registerScavoldI18n } from "../composables/useI18n.js";
+// Populated at build time by the scavold:external-redirect-map Vite plugin.
+// Maps site-relative paths ("/de/links") to their external redirect targets.
+import externalRedirectMap from "virtual:scavold/external-redirect-map";
+
+/**
+ *
+ */
+export async function enhanceApp( { app, router } ) {
+	registerScavoldI18n();
+
+	const items = Object.entries( import.meta.glob( "../components/*.vue" ) );
+
+	await Promise.all( items.map( ( [ path, importer ] ) => {
+		const name = path.replace( /^.*\/|\.vue$/g, "" );
+
+		return importer().then( module => app.component( name, module.default ) );
+	} ) );
+
+	// Intercept SPA navigation to external redirect pages using VitePress's own
+	// router hook.  VitePress's click handler runs in window capture phase and
+	// calls go() → onBeforeRouteChange synchronously before doing anything else.
+	// We are therefore still inside the user-gesture context, so window.open()
+	// has full browser permission.  Returning false cancels the VitePress
+	// navigation so the current page stays in place.
+	//
+	// A capture-phase DOM listener on document is NOT sufficient here because
+	// VitePress's own listener is on window with { capture: true }, which fires
+	// earlier in the propagation chain — stopPropagation at document level is
+	// already too late.
+	if ( typeof window !== "undefined" && router ) {
+		// The very first call to onBeforeRouteChange is the initial router.go()
+		// from createApp() — not a user navigation. Direct-page-load redirects
+		// are already handled by <meta http-equiv="refresh"> in the head, so we
+		// must let this call pass through unconditionally.
+		let initialNavDone = false;
+		const prevHook = router.onBeforeRouteChange;
+		router.onBeforeRouteChange = async ( href ) => {
+			if ( !initialNavDone ) {
+				initialNavDone = true;
+				return;
+			}
+			if ( prevHook && await prevHook( href ) === false ) return false;
+			let url;
+			try { url = new URL( href, location.href ); }
+			catch { return; }
+			// Only intercept same-origin navigation; let the browser handle
+			// any already-external hrefs natively.
+			if ( url.origin !== location.origin ) return;
+			// Strip trailing slash and .html suffix — VitePress's normalizeHref
+			// appends .html when cleanUrls is disabled, but the redirect map
+			// always stores bare paths (e.g. "/de/links", not "/de/links.html").
+			const path = url.pathname.replace( /\.html$/, "" ).replace( /\/$/, "" ) || "/";
+			const target = externalRedirectMap[path] ?? externalRedirectMap[path + "/"];
+			if ( !target ) return;
+			window.open( target, "_blank", "noopener,noreferrer" );
+			return false; // cancel VitePress SPA navigation
+		};
+	}
+}

package/lib/markdown.js

@@ -0,0 +1,22 @@
+/**
+ * Replaces named renderer rule of provided markdown-it instance with the given
+ * callback invoking the replaced rule in case the given one returns undefined.
+ *
+ * @param {import('markdown-it')} markdown - instance of markdown-it
+ * @param {string} ruleName - name of the rule to patch
+ * @param {Function} patchFn - callback replacing named rule, may return nothing/undefined to use result of replaced rule
+ * @returns {void}
+ */
+export function patchRenderer( markdown, ruleName, patchFn ) {
+	const defaultHandler = markdown.renderer.rules[ruleName];
+
+	markdown.renderer.rules[ruleName] = ( tokens, idx, options, env, slf ) => {
+		const patch = patchFn( defaultHandler, tokens, idx, options, env, slf );
+
+		if ( patch === undefined ) {
+			return defaultHandler( tokens, idx, options, env, slf );
+		}
+
+		return patch;
+	};
+}

package/lib/media.js

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { join, basename, extname } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import sharp from "sharp";
+
+const DEFAULT_WIDTHS = [ 320, 640, 960, 1280, 1920 ];
+
+/**
+ * Returns the public output folder for generated image variants.
+ *
+ * @param {string} root project root (where .vitepress lives)
+ * @param {string} [staticDir] absolute path to the static/public folder (vite.publicDir)
+ * @returns {string}
+ */
+function variantsPublicDir( root, staticDir ) {
+	return join( staticDir ?? join( root, ".vitepress", "public" ), "media" );
+}
+
+/**
+ * Derives a stable 8-character hex hash from the source file content.
+ *
+ * @param {string} filePath absolute path to source file
+ * @returns {string}
+ */
+function contentHash( filePath ) {
+	return createHash( "sha1" ).update( readFileSync( filePath ) ).digest( "hex" ).slice( 0, 8 );
+}
+
+/**
+ * Converts a filename to kebab-case.
+ *
+ * @param {string} name filename without extension
+ * @returns {string}
+ */
+export function toKebabCase( name ) {
+	return name
+		.replace( /([a-z])([A-Z])/g, "$1-$2" )
+		.replace( /[\s_]+/g, "-" )
+		.toLowerCase();
+}
+
+/**
+ * Generates scaled image variants using sharp and returns srcset data.
+ * Skips generating a variant if the output file already exists (content-hash
+ * in the name means existence implies correctness).
+ *
+ * @param {string} srcPath absolute path to source image
+ * @param {string} outDir absolute path to public output folder
+ * @param {number[]} widths list of target widths
+ * @returns {Promise<{srcset: string, webpSrcset: string, fallbackSrc: string}>}
+ */
+async function generateVariants( srcPath, outDir, widths ) {
+	mkdirSync( outDir, { recursive: true } );
+
+	const hash = contentHash( srcPath );
+	const ext = extname( srcPath ).toLowerCase().replace( ".", "" ) || "jpg";
+	const base = toKebabCase( basename( srcPath, extname( srcPath ) ) );
+	const image = sharp( srcPath );
+	const meta = await image.metadata();
+	const sourceWidth = meta.width ?? Infinity;
+
+	const targets = widths.filter( w => w <= sourceWidth );
+
+	if ( targets.length === 0 || targets[targets.length - 1] < sourceWidth ) {
+		targets.push( Math.min( sourceWidth, widths[widths.length - 1] ) );
+	}
+
+	const srcsetParts = [];
+	const webpSrcsetParts = [];
+
+	await Promise.all( targets.map( async width => {
+		const outName = `${base}--${width}w-${hash}`;
+		const outOrig = join( outDir, `${outName}.${ext}` );
+		const outWebp = join( outDir, `${outName}.webp` );
+
+		const resized = image.clone().resize( { width, withoutEnlargement: true } );
+
+		await Promise.all( [
+			existsSync( outOrig ) ? Promise.resolve() : resized.clone().toFile( outOrig ),
+			existsSync( outWebp ) ? Promise.resolve() : resized.clone().webp().toFile( outWebp ),
+		] );
+
+		srcsetParts.push( { width, url: `/media/${outName}.${ext}` } );
+		webpSrcsetParts.push( { width, url: `/media/${outName}.webp` } );
+	} ) );
+
+	srcsetParts.sort( ( a, b ) => a.width - b.width );
+	webpSrcsetParts.sort( ( a, b ) => a.width - b.width );
+
+	return {
+		srcset: srcsetParts.map( ( { width, url } ) => `${url} ${width}w` ).join( ", " ),
+		webpSrcset: webpSrcsetParts.map( ( { width, url } ) => `${url} ${width}w` ).join( ", " ),
+		fallbackSrc: srcsetParts[srcsetParts.length - 1].url,
+	};
+}
+
+/**
+ * Extracts local image paths from a markdown source string.
+ *
+ * @param {string} source markdown source
+ * @returns {string[]} list of image src values found
+ */
+export function extractImageSrcs( source ) {
+	const srcs = [];
+
+	for ( const match of source.matchAll( /!\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g ) ) {
+		srcs.push( match[1] );
+	}
+
+	return srcs;
+}
+
+/**
+ * Sets up media handling for a Scavold-based VitePress site.
+ *
+ * Call `warmUp(pages)` in a buildStart hook before pages are rendered so that
+ * all variant data is in the sync cache by the time the markdown renderer runs.
+ * `collectImage()` is then synchronous and returns cached data immediately.
+ *
+ * @param {object} config raw VitePress user config (with optional mediaDir)
+ * @param {object} [options]
+ * @param {number[]} [options.widths] target widths for image variants
+ * @param {string} [options.sizes] default sizes attribute value
+ * @returns {{ warmUp: function, collectImage: function }}
+ */
+export function useMedia( config, options = {} ) {
+	const widths = options.widths ?? DEFAULT_WIDTHS;
+	const defaultSizes = options.sizes ?? "100vw";
+	const mediaDir = config.mediaDir ?? config.srcDir ?? "media";
+	const root = config.root ?? process.cwd?.() ?? ".";
+	const outDir = variantsPublicDir( root, config.vite?.publicDir );
+
+	/** @type {Map<string, {src: string, srcset: string, webpSrcset: string, sizes: string}>} */
+	const cache = new Map();
+
+	/**
+	 * Resolves a markdown image src to an absolute filesystem path, or null for
+	 * remote URLs.
+	 *
+	 * @param {string} imageUrl
+	 * @returns {string|null}
+	 */
+	function resolveImagePath( imageUrl ) {
+		if ( /^[a-z]+:\/\//i.test( imageUrl ) ) {
+			return null;
+		}
+
+		return imageUrl.startsWith( "/" )
+			? join( root, mediaDir, imageUrl.slice( 1 ) )
+			: join( root, mediaDir, imageUrl );
+	}
+
+	/**
+	 * Processes a single image path into the cache.
+	 *
+	 * @param {string} imageUrl
+	 * @returns {Promise<void>}
+	 */
+	async function process( imageUrl ) {
+		if ( cache.has( imageUrl ) ) {
+			return;
+		}
+
+		const filePath = resolveImagePath( imageUrl );
+
+		if ( !filePath ) {
+			return;
+		}
+
+		if ( !existsSync( filePath ) ) {
+			console.error( "image %s is missing (resolved to %s)", imageUrl, filePath );
+			return;
+		}
+
+		const variants = await generateVariants( filePath, outDir, widths );
+
+		cache.set( imageUrl, {
+			src: variants.fallbackSrc,
+			srcset: variants.srcset,
+			webpSrcset: variants.webpSrcset,
+			sizes: defaultSizes,
+		} );
+	}
+
+	return {
+		/**
+		 * Pre-processes all local images found in the given page files so the
+		 * sync cache is populated before any markdown rendering begins.
+		 * Call this from the VitePress buildStart hook.
+		 *
+		 * @param {string[]} pageFiles absolute paths to markdown source files
+		 * @returns {Promise<void>}
+		 */
+		async warmUp( pageFiles ) {
+			const srcs = new Set();
+
+			await Promise.all( pageFiles.map( async file => {
+				const source = await readFile( file, "utf-8" );
+
+				for ( const src of extractImageSrcs( source ) ) {
+					srcs.add( src );
+				}
+			} ) );
+
+			await Promise.all( [ ...srcs ].map( src => process( src ) ) );
+		},
+
+		/**
+		 * Returns cached variant data for a local image src, or null for remote
+		 * or unrecognised sources. Must be called after warmUp() has completed.
+		 *
+		 * @param {string} imageUrl value of the src attribute from markdown
+		 * @param {string} [sizesOverride] per-image sizes attribute override
+		 * @returns {{src: string, srcset: string, webpSrcset: string, sizes: string}|null}
+		 */
+		collectImage( imageUrl, sizesOverride ) {
+			const data = cache.get( imageUrl );
+
+			if ( !data ) {
+				return null;
+			}
+
+			if ( sizesOverride ) {
+				return { ...data, sizes: sizesOverride };
+			}
+
+			return data;
+		},
+	};
+}