scavold 0.2.0-rc.1

package/composables/useVideo.js

@@ -0,0 +1,89 @@
+import { computed } from "vue";
+import { containerProps } from "./useContainer.js";
+
+/**
+ * Props definition for video container components. Spread into `defineProps`
+ * alongside any component-specific props.
+ */
+export const videoProps = {
+	...containerProps,
+
+	/** URL of the video file. */
+	dataSrc: { type: String, default: "" },
+
+	/** URL of the poster image shown before playback. */
+	dataPoster: { type: String, default: "" },
+
+	/** Play automatically when the page loads. Implies muted. */
+	dataAutoplay: { type: String, default: null },
+
+	/** Loop the video when it ends. */
+	dataLoop: { type: String, default: null },
+
+	/** Mute the audio track. */
+	dataMuted: { type: String, default: null },
+
+	/** Render as a background: the video fills the block and the container's
+	 * body content is layered on top of it. */
+	dataOverlay: { type: String, default: null },
+
+	/** Show the native playback controls. Always present in the default player;
+	 * opt-in in overlay mode, where a background video is normally chrome-free. */
+	dataControls: { type: String, default: null },
+
+	/** Hint for preloading: "none", "metadata" (default), or "auto". */
+	dataPreload: { type: String, default: null },
+
+	/** Accessible label for the video element, announced by screen readers.
+	 * Use when the surrounding context does not already describe the video. */
+	dataLabel: { type: String, default: null },
+};
+
+/**
+ * Composable for video container components.
+ *
+ * Parses the props emitted by the markdown-it container renderer for a
+ * `:::video` block and exposes derived values ready for binding:
+ *
+ *   - `src`      — video URL
+ *   - `poster`   — poster image URL, or empty string
+ *   - `autoplay` — boolean, always implies muted
+ *   - `loop`     — boolean
+ *   - `muted`    — boolean (forced true when autoplay is true)
+ *   - `preload`  — "none" | "metadata" | "auto"
+ *   - `overlay`  — boolean, render the video as a background behind the slot
+ *   - `controls` — boolean, always true in the default player; opt-in in overlay mode
+ *
+ * Custom video components should call this composable so they share identical
+ * attribute resolution without duplicating the logic.
+ *
+ * @param {object} props  reactive props from defineProps
+ * @returns {{ src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel }}
+ */
+export function useVideo( props ) {
+	const src = computed( () => props.dataSrc ?? "" );
+	const poster = computed( () => props.dataPoster ?? "" );
+
+	const autoplay = computed( () => props.dataAutoplay != null );
+	const loop = computed( () => props.dataLoop != null );
+
+	// autoplay requires muted to be allowed by browsers without user gesture
+	const muted = computed( () => autoplay.value || props.dataMuted != null );
+
+	const PRELOAD_VALUES = new Set( [ "none", "metadata", "auto" ] );
+	const preload = computed( () =>
+		PRELOAD_VALUES.has( props.dataPreload ) ? props.dataPreload : "metadata"
+	);
+
+	const overlay = computed( () => props.dataOverlay != null );
+
+	// The default player always shows controls; a background video is chrome-free
+	// unless the author opts back in with the `controls` flag.
+	const controls = computed( () =>
+		overlay.value ? props.dataControls != null : true
+	);
+
+	const ariaLabel = computed( () => props.dataLabel ?? undefined );
+
+	return { src, poster, autoplay, loop, muted, preload, overlay, controls, ariaLabel };
+}

package/index.d.ts

@@ -0,0 +1,43 @@
+import type { PageData } from "vitepress";
+
+export module Scavold {
+	/** VitePress user config, as accepted by {@link augmentConfig}. */
+	type UserConfig = import( "vitepress" ).UserConfig;
+
+	interface HierarchyNode {
+		parent?: HierarchyNode;
+		isPage: boolean;
+		path: string;
+		subs?: { [path: string]: HierarchyNode };
+		locale?: string;
+		/** Display title for the page — from frontmatter `title` or the first heading. */
+		title?: string;
+		/** Navigation label for the page — from frontmatter `label`, falls back to `title`. */
+		label?: string;
+		/** Normalised alias output path (e.g. `de/impressum.md`) when `url` is declared in frontmatter. Used as the page's href instead of its source path. */
+		url?: string;
+		frontmatter?: { [key: string]: any };
+	}
+
+	interface AugmentedPageData extends PageData {
+		hierarchy: HierarchyNode;
+	}
+
+	interface MenuItem {
+		node: HierarchyNode;
+		active: boolean;
+		current: boolean;
+		children: MenuItem[];
+	}
+
+	type LocaleDetection = "auto" | "explicit" | "inherited" | "global";
+
+	interface LocaleLink {
+		/** BCP 47 locale code. */
+		locale: string;
+		/** Resolved href for this locale. */
+		href: string;
+		/** True when this locale matches the current page's locale. */
+		current: boolean;
+	}
+}

package/l10n/de.json

@@ -0,0 +1,6 @@
+{
+	"nav": {
+		"breadcrumb": "Navigationspfad",
+		"locale": "Sprache"
+	}
+}

package/l10n/en.json

@@ -0,0 +1,6 @@
+{
+	"nav": {
+		"breadcrumb": "Breadcrumb",
+		"locale": "Language"
+	}
+}

package/lib/config.d.ts

@@ -0,0 +1,17 @@
+import type { UserConfig } from "vitepress";
+
+export interface AugmentOptions {
+	/**
+	 * Explicit container-name → component-name overrides, merged on top of
+	 * Scavold's defaults and any names declared in `.cratly.config.yaml`.
+	 */
+	containers?: Record<string, string>;
+}
+
+/**
+ * Augments a VitePress user config with all Scavold features: derives `srcDir`
+ * and `vite.publicDir` from `.cratly.config.yaml`, registers the image
+ * processing plugin and the Markdown container extensions, and emits the
+ * section-type manifest read by the cratly editor.
+ */
+export function augmentConfig( rawConfig: UserConfig, options?: AugmentOptions ): Promise<UserConfig>;

package/lib/config.js

@@ -0,0 +1,396 @@
+import { join, relative, resolve } from "node:path";
+import { dirname, join as joinPosix } from "node:path/posix";
+import { readFile } from "node:fs/promises";
+import { readdirSync, readFileSync } from "node:fs";
+import { clearCache, compileHierarchy, compileRedirects, sourceFolder } from "./pages.js";
+import { useMedia } from "./media.js";
+import { patchRenderer } from "./markdown.js";
+import { registerContainers, resolveContainerMap } from "./containers.js";
+import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
+import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
+
+// Scavold's own version, reported under `adapter.version` in the emitted
+// section-type manifest.
+const SCAVOLD_VERSION = JSON.parse(
+	readFileSync( new URL( "../package.json", import.meta.url ), "utf-8" ),
+).version;
+
+// ─── External-redirect map virtual module ────────────────────────────────────
+// During Vite's browser bundle step the plugin exposes a JSON map of
+//   { "/site/relative/path": "https://external-url" }
+// for every page whose frontmatter has a plain-string external redirect.
+// lib/index.js imports this map statically so the capture-phase click listener
+// can call window.open() synchronously within the user's click event, giving
+// the browser full user-gesture context and avoiding popup blockers entirely.
+
+const REDIRECT_MAP_VIRTUAL_ID = "virtual:scavold/external-redirect-map";
+const REDIRECT_MAP_RESOLVED_ID = "\0" + REDIRECT_MAP_VIRTUAL_ID;
+
+/**
+ * Returns the scalar string value after "redirect:" on the same YAML line,
+ * or null if the frontmatter has no scalar redirect (e.g. block-style locale
+ * redirect maps).
+ *
+ * @param {string} content Raw markdown file content
+ * @returns {string|null}
+ */
+function extractFrontmatterRedirect( content ) {
+	const fmMatch = content.match( /^---\r?\n([\s\S]*?)\r?\n---/ );
+	if ( !fmMatch ) return null;
+	const rdMatch = fmMatch[1].match( /^redirect:\s*(.+)$/m );
+	if ( !rdMatch ) return null;
+	let value = rdMatch[1].trim();
+	// Strip optional surrounding quotes
+	if ( ( value.startsWith( '"' ) && value.endsWith( '"' ) ) ||
+	     ( value.startsWith( "'" ) && value.endsWith( "'" ) ) ) {
+		value = value.slice( 1, -1 );
+	}
+	return value || null;
+}
+
+/**
+ * Recursively walks srcDir and fills map with { urlPath → externalUrl } for
+ * every .md file whose frontmatter redirect is an external URL.
+ *
+ * @param {string} dir Absolute path to scan
+ * @param {string} base Absolute srcDir root (for computing site-relative path)
+ * @param {Record<string,string>} map Result accumulator
+ */
+function walkMdFilesForRedirects( dir, base, map ) {
+	for ( const entry of readdirSync( dir, { withFileTypes: true } ) ) {
+		const full = join( dir, entry.name );
+		if ( entry.isDirectory() ) {
+			if ( !entry.name.startsWith( "." ) && entry.name !== "node_modules" ) {
+				walkMdFilesForRedirects( full, base, map );
+			}
+		} else if ( entry.name.endsWith( ".md" ) ) {
+			let content;
+			try { content = readFileSync( full, "utf8" ); }
+			catch { continue; }
+			const redirect = extractFrontmatterRedirect( content );
+			if ( redirect && isExternalUrl( redirect ) ) {
+				const rel = relative( base, full ).replace( /\\/g, "/" );
+				const urlPath = "/" + rel.replace( /index\.md$/, "" ).replace( /\.md$/, "" );
+				map[urlPath] = redirect;
+			}
+		}
+	}
+}
+
+/**
+ * Creates a Vite plugin that exposes virtual:scavold/external-redirect-map.
+ * The module is built by scanning pagesDir for .md files with external
+ * redirect frontmatter.  Invalidated in dev mode on any .md file change so
+ * the next full-reload (triggered by mediaPlugin) picks up the new map.
+ *
+ * @param {string} pagesDir Absolute path to the VitePress srcDir
+ * @returns {import("vite").Plugin}
+ */
+function createExternalRedirectMapPlugin( pagesDir ) {
+	return {
+		name: "scavold:external-redirect-map",
+		resolveId( id ) {
+			if ( id === REDIRECT_MAP_VIRTUAL_ID ) return REDIRECT_MAP_RESOLVED_ID;
+		},
+		load( id ) {
+			if ( id !== REDIRECT_MAP_RESOLVED_ID ) return;
+			const map = {};
+			try { walkMdFilesForRedirects( pagesDir, pagesDir, map ); }
+			catch { /* srcDir not accessible yet — return empty map */ }
+			return `export default ${JSON.stringify( map )}`;
+		},
+		configureServer( server ) {
+			// Invalidate on .md changes so the next full-reload (triggered by
+			// mediaPlugin.handleHotUpdate) picks up the updated map.
+			server.watcher.on( "change", path => {
+				if ( !path.endsWith( ".md" ) ) return;
+				const mod = server.moduleGraph.getModuleById( REDIRECT_MAP_RESOLVED_ID );
+				if ( mod ) server.moduleGraph.invalidateModule( mod );
+			} );
+		},
+	};
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts an optional sizes override from a markdown image title string.
+ * Recognises the pattern: sizes=VALUE or sizes="VALUE"
+ *
+ * @param {string|null} title
+ * @returns {string|undefined}
+ */
+function parseSizesFromTitle( title ) {
+	if ( !title ) {
+		return undefined;
+	}
+
+	const match = title.match( /(?:^|\s)sizes=(?:"([^"]+)"|(\S+))/ );
+
+	return match?.[1] ?? match?.[2] ?? undefined;
+}
+
+/**
+ * Augments provided VitePress configuration to integrate extended theme
+ * features.
+ *
+ * @param {object} rawConfig VitePress user config
+ * @param {object} [options]
+ * @param {Object<string,string>} [options.containers] explicit container-name →
+ *   component-name overrides, merged on top of Scavold defaults and any names
+ *   declared in .crate.config.yaml
+ */
+export async function augmentConfig( rawConfig, options = {} ) {
+	// Read .crate.config.yaml for structural config and container declarations (Tier 2)
+	let crateContainers = {};
+	let crateSrcDir = null;
+	let crateStaticDir = null;
+	let crateImageSizes = null;
+	let crateImageWidths = null;
+
+	try {
+		const { readFile } = await import( "node:fs/promises" );
+		const YAML = ( await import( "yaml" ) ).default;
+		const raw = await readFile( join( process.cwd(), ".cratly.config.yaml" ), "utf-8" );
+		const crate = YAML.parse( raw ) ?? {};
+		crateContainers = crate.containers ?? {};
+		crateSrcDir = crate.pages_folder ?? null;
+		crateStaticDir = crate.static_folder ?? null;
+		crateImageSizes = crate.image_sizes ?? null;
+		crateImageWidths = crate.image_widths ?? null;
+	} catch {
+		// file absent or unparseable — proceed with defaults
+	}
+
+	const containerMap = resolveContainerMap( crateContainers, options.containers );
+
+	// Apply srcDir from crate config if not already set in rawConfig
+	const srcDir = rawConfig.srcDir ?? crateSrcDir ?? undefined;
+
+	// Prevent VitePress/Vite from defaulting publicDir to {srcDir}/public when
+	// content lives in a subfolder — static assets must not appear inside the
+	// pages folder. VitePress passes srcDir as Vite's root, so publicDir must be
+	// an absolute path to be unambiguous. Derived from static_folder in
+	// .crate.config.yaml; falls back to "public" at the project root only when
+	// srcDir is a subfolder and no explicit value is set by the caller.
+	const staticFolder = crateStaticDir ?? ( srcDir && srcDir !== "." ? "public" : null );
+	const vitePublicDir = rawConfig.vite?.publicDir
+		?? ( staticFolder ? resolve( process.cwd(), staticFolder ) : undefined );
+
+	// Resolved config carries the derived srcDir so pages.js helpers see it correctly.
+	// The vite.plugins array is built separately below after media is initialised.
+	const resolvedConfig = {
+		...rawConfig,
+		...(srcDir !== undefined && { srcDir }),
+		vite: {
+			...rawConfig.vite,
+			...(vitePublicDir !== undefined && { publicDir: vitePublicDir }),
+		},
+	};
+
+	const media = useMedia( resolvedConfig, {
+		...( crateImageSizes != null && { sizes: crateImageSizes } ),
+		...( crateImageWidths != null && { widths: crateImageWidths } ),
+	} );
+
+	async function warmUpMedia() {
+		const pagesDir = sourceFolder( resolvedConfig );
+		const { glob } = await import( "node:fs/promises" );
+		const pageFiles = ( await Array.fromAsync( glob( "**/*.md", { cwd: pagesDir } ) ) )
+			.map( f => join( pagesDir, f ) );
+
+		await media.warmUp( pageFiles );
+	}
+
+	// VitePress's internal markdown LRU cache clear function — not public API
+	// but needed to force re-compilation of all pages on .md changes.
+	let clearVPCache;
+
+	/** @type {import("vite").Plugin} */
+	const mediaPlugin = {
+		name: "scavold:media",
+		async buildStart() {
+			await warmUpMedia();
+		},
+		async configureServer( server ) {
+			server.httpServer?.once( "listening", () => warmUpMedia() );
+
+			// VitePress does not expose its internal markdown LRU cache publicly.
+			// We locate the chunk by finding whichever dist/node chunk exports a
+			// function named `clearCache` (exported as an alias). If VitePress
+			// ever makes this public or changes its chunk layout this will degrade
+			// gracefully — pages will still reload, hierarchy just won't update
+			// until the server is restarted.
+			// TODO: remove once https://github.com/vuejs/vitepress/issues/XXXX
+			// is resolved and VitePress exposes clearCache publicly.
+			try {
+				const { readdir } = await import( "node:fs/promises" );
+				const { createRequire } = await import( "node:module" );
+				const require = createRequire( import.meta.url );
+				const vpNodeDir = new URL( "../../dist/node/", import.meta.resolve( "vitepress" ) );
+				const chunks = ( await readdir( new URL( ".", vpNodeDir ) ) )
+					.filter( f => f.startsWith( "chunk-" ) && f.endsWith( ".js" ) );
+
+				for ( const chunk of chunks ) {
+					const mod = await import( new URL( chunk, vpNodeDir ).href );
+					const fn = Object.values( mod ).find( v => typeof v === "function" && v.length <= 1 && v.toString().includes( "cache$1" ) );
+
+					if ( fn ) {
+						clearVPCache = fn;
+						break;
+					}
+				}
+
+				if ( !clearVPCache ) {
+					console.warn( "[scavold] could not locate VitePress internal markdown cache — hierarchy changes may require a server restart to take effect" );
+				}
+			} catch {
+				console.warn( "[scavold] could not locate VitePress internal markdown cache — hierarchy changes may require a server restart to take effect" );
+			}
+		},
+		handleHotUpdate( { file, server } ) {
+			if ( !file.endsWith( ".md" ) ) {
+				return;
+			}
+
+			warmUpMedia();
+			clearVPCache?.();
+
+			// Invalidate all .md modules and trigger a full reload so the
+			// browser re-requests the current page, causing transformPageData
+			// to run fresh for it with the updated hierarchy.
+			const mdModules = [];
+
+			for ( const mod of server.moduleGraph.idToModuleMap.values() ) {
+				if ( mod.file?.endsWith( ".md" ) ) {
+					server.moduleGraph.invalidateModule( mod );
+					mdModules.push( mod );
+				}
+			}
+
+			server.ws.send( { type: "full-reload" } );
+
+			return mdModules;
+		},
+	};
+
+	const pagesDir = sourceFolder( resolvedConfig );
+
+	// Emit the section-type manifest (.cratly/sections.json) so the cratly
+	// editor can render typed controls per section kind. Built from Scavold's
+	// built-in sections merged with the site's container declarations. Written
+	// at build start and once when the dev server starts listening.
+	async function emitSectionManifest() {
+		try {
+			const manifest = buildSectionManifest( crateContainers, { adapterVersion: SCAVOLD_VERSION } );
+			await writeSectionManifest( process.cwd(), manifest );
+		} catch ( error ) {
+			console.warn( "[scavold] could not write .cratly/sections.json —", error.message );
+		}
+	}
+
+	/** @type {import("vite").Plugin} */
+	const sectionManifestPlugin = {
+		name: "scavold:section-manifest",
+		async buildStart() {
+			await emitSectionManifest();
+		},
+		configureServer( server ) {
+			server.httpServer?.once( "listening", () => emitSectionManifest() );
+		},
+	};
+
+	return {
+		...resolvedConfig,
+		vite: {
+			...resolvedConfig.vite,
+			plugins: [
+				...( rawConfig.vite?.plugins ?? [] ),
+				mediaPlugin,
+				sectionManifestPlugin,
+				createExternalRedirectMapPlugin( pagesDir ),
+			],
+		},
+		rewrites: {
+			...rawConfig?.rewrites,
+			...await compileRedirects( resolvedConfig ),
+		},
+		buildEnd: rawConfig.buildEnd,
+		async transformPageData( pageData, context ) {
+			clearCache();
+
+			// Inject head tags for string-form redirects so the browser acts
+			// immediately on a direct page load without any script or user interaction.
+			//
+			// Internal targets → <script>location.replace(…)</script>
+			//   Fires synchronously before rendering.  VitePress/@unhead/vue
+			//   re-executes <script> tags on every SPA navigation, but the
+			//   capture-phase click interceptor in lib/index.js cancels the router
+			//   navigation before this page is ever reached via SPA, so the
+			//   re-execution never causes a double-redirect.
+			//
+			// External targets → <meta http-equiv="refresh" content="0;url=…">
+			//   The browser processes <meta http-equiv="refresh"> only during initial
+			//   HTML parsing, not when @unhead/vue re-inserts it on SPA navigation,
+			//   so it is safe to include unconditionally.  On direct page loads the
+			//   tab redirects automatically.  SPA navigation is intercepted by the
+			//   click listener before the router fires, so this page never mounts
+			//   during in-app use.
+			//
+			// The redirect value can be either:
+			//   - a site-relative URL  ("/de/jobs")  — written by the Cratly editor
+			//   - a relative .md path  ("jobs.md")   — written by hand in frontmatter
+			//   - an absolute external URL            — e.g. "https://example.com"
+			const redirect = pageData.frontmatter?.redirect;
+			if ( typeof redirect === "string" ) {
+				if ( isExternalUrl( redirect ) ) {
+					pageData.frontmatter.head = [
+						...( pageData.frontmatter.head ?? [] ),
+						[ "meta", { "http-equiv": "refresh", content: `0;url=${redirect}` } ],
+					];
+				} else {
+					let target;
+					if ( redirect.startsWith( "/" ) ) {
+						target = servableRedirectTarget( redirect );
+					} else {
+						const dir = dirname( pageData.relativePath );
+						const resolved = joinPosix( dir === "." ? "" : dir, redirect );
+						target = servableRedirectTarget( "/" + resolved.replace( /\/index\.md$/, "/" ).replace( /\.md$/, "" ) );
+					}
+					pageData.frontmatter.head = [
+						...( pageData.frontmatter.head ?? [] ),
+						[ "script", {}, `location.replace(${JSON.stringify( target )})` ],
+					];
+				}
+			}
+
+			return {
+				hierarchy: await compileHierarchy( resolvedConfig, context.siteConfig.pages ),
+			};
+		},
+		markdown: {
+			config( md ) {
+				// see https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.mjs
+
+				patchRenderer( md, "image", ( defaultHandler, tokens, idx, options, ...args ) => {
+					const token = tokens[idx];
+					const sizesOverride = parseSizesFromTitle( token.attrGet( "title" ) );
+					const data = media.collectImage( token.attrGet( "src" ), sizesOverride );
+
+					if ( data ) {
+						token.tag = "ScavoldImage";
+						token.attrSet( "src", data.src );
+						token.attrSet( "srcset", data.srcset );
+						token.attrSet( "webp-srcset", data.webpSrcset );
+						token.attrSet( "sizes", data.sizes );
+						options = { ...options, xhtmlOut: true };
+					}
+
+					return defaultHandler( tokens, idx, options, ...args );
+				} );
+
+				registerContainers( md, containerMap );
+			},
+		},
+	};
+}

package/lib/containers.js

@@ -0,0 +1,128 @@
+import ContainerPlugin from "markdown-it-container";
+import { parseKeyValuePairs } from "./parser.js";
+
+/**
+ * HTML sectioning element names that Scavold maps to thin wrapper components
+ * by default. Each maps to `Scavold{Name}` unless overridden.
+ */
+export const SECTIONING_ELEMENTS = new Set( [
+	"article",
+	"aside",
+	"footer",
+	"header",
+	"main",
+	"nav",
+	"section",
+] );
+
+/**
+ * Builds the default container-name → component-name map from the set of
+ * built-in sectioning element names plus other built-in containers.
+ *
+ * @returns {Object<string,string>}
+ */
+function defaultContainerMap() {
+	const map = {};
+
+	for ( const name of SECTIONING_ELEMENTS ) {
+		map[name] = `Scavold${name[0].toUpperCase()}${name.slice( 1 )}`;
+	}
+
+	map.video = "ScavoldVideo";
+
+	return map;
+}
+
+/**
+ * Resolves a container name to the Vue component tag to emit, using the
+ * provided map. Falls back to ScavoldContainer for unknown names.
+ *
+ * @param {string} name container name from markdown
+ * @param {Object<string,string>} map resolved name→component map
+ * @returns {string} component tag name
+ */
+function resolveTag( name, map ) {
+	return map[name] ?? "ScavoldContainer";
+}
+
+/**
+ * Renders the opening or closing tag for a container token.
+ *
+ * @param {string} tag component tag to emit
+ * @param {import('markdown-it/lib/token')} token
+ * @param {string} containerName the original container name from markdown
+ * @returns {string}
+ */
+function renderToken( tag, token, containerName ) {
+	if ( token.nesting !== 1 ) {
+		return `</${tag}>\n`;
+	}
+
+	const args = parseKeyValuePairs( token.info.trim().replace( /^\S+\s*/, "" ) );
+
+	const classes = Object.keys( args )
+		.filter( key => args[key] === true )
+		.join( " " );
+
+	const attrs = Object.entries( args )
+		.filter( ( [ , value ] ) => value && value !== true )
+		.map( ( [ key, value ] ) => `data-${key}="${value}"` );
+
+	attrs.push( `data-container="${containerName}"` );
+
+	if ( classes ) {
+		attrs.push( `class="${classes}"` );
+	}
+
+	return `<${tag} ${attrs.join( " " )}>\n`;
+}
+
+/**
+ * Registers markdown-it-container plugins for all container names in the
+ * provided map, plus ScavoldContainer as the catch-all fallback for any name
+ * not in the map.
+ *
+ * @param {import('markdown-it')} md markdown-it instance
+ * @param {Object<string,string>} containerMap resolved name→component map
+ */
+export function registerContainers( md, containerMap ) {
+	for ( const [ name, tag ] of Object.entries( containerMap ) ) {
+		md.use( ContainerPlugin, name, {
+			render: ( tokens, index ) => renderToken( tag, tokens[index], name ),
+		} );
+	}
+}
+
+/**
+ * Merges the Scavold default container map with site-level declarations from
+ * .crate.config.yaml and an explicit developer-supplied override map.
+ *
+ * Resolution order (last wins):
+ *   1. Scavold built-in sectioning element defaults
+ *   2. Names declared in crateConfig.containers (mapped to Scavold{Name})
+ *   3. Explicit overrides passed directly to augmentConfig
+ *
+ * @param {object} [crateContainers] containers block from .crate.config.yaml
+ * @param {Object<string,string>} [overrides] explicit name→component overrides
+ * @returns {Object<string,string>}
+ */
+export function resolveContainerMap( crateContainers = {}, overrides = {} ) {
+	const map = defaultContainerMap();
+
+	for ( const [ name, value ] of Object.entries( crateContainers ) ) {
+		if ( typeof value === "string" ) {
+			// shorthand: "name: ComponentName" — treat string as explicit component override
+			map[name] = value;
+		} else if ( value?.component ) {
+			// object form with explicit component key
+			map[name] = value.component;
+		} else if ( !map[name] ) {
+			// object form without component key — register with default naming convention
+			map[name] = `Scavold${name[0].toUpperCase()}${name.slice( 1 )}`;
+		}
+	}
+
+	Object.assign( map, overrides );
+
+	return map;
+}