scavold 0.2.0-rc.1 → 0.2.0-rc.3

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to Scavold are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While the version stays below `1.0.0` and carries a pre-release suffix, breaking
+changes may occur in any release.
+
+## [0.2.0-rc.3] — 2026-08-09
+
+### Added
+
+- Media that is not an image is published. Files an author uploads into the media folder
+  — PDFs, videos, archives — are copied into the static output keeping their path, and
+  references to them are rewritten to the URL the built site serves: Markdown links,
+  and container arguments declared as `media-file` such as a video's `src` or `poster`.
+  Previously only Markdown image syntax was handled, so a linked document or a video
+  resolved to a dead URL although the editor offered exactly that reference. Where a
+  single URL is needed instead of a srcset — a `poster`, a link to an image — the
+  largest generated variant is used.
+
+### Fixed
+
+- Flag arguments on a container reach components that declare them as props. Bare words
+  used to become the container's `class` only, while `useVideo()` reads its booleans
+  from `data-*` props — so the documented `::: video src=… overlay autoplay loop`
+  rendered a plain inline player with no background mode, no autoplay and no loop, and
+  failed silently. Flags are now emitted as an empty `data-<flag>` attribute in addition
+  to the class. A flag a component does not declare as a prop shows up in the markup as
+  an empty attribute (`<section class="highlight" data-highlight>`).
+
+### Added
+
+- Container blocks work with any name, declared or not: an undeclared name is rendered
+  by `ScavoldContainer` instead of leaving its fences in the page as literal text. To
+  keep a typo from silently becoming a `<div>`, the build reports each undeclared name
+  once; declaring it in `.cratly.config.yaml` silences the report and adds typed
+  properties for the editor.
+
+### Fixed
+
+- `registerContainers()` and the component reference described `ScavoldContainer` as a
+  catch-all fallback, which it was not — no rule was registered for unknown names.
+
+## [0.2.0-rc.2] — 2026-08-06
+
+### Fixed
+
+- `media_folder` from `.cratly.config.yaml` is honoured again. `augmentConfig()` read
+  every other folder declaration but this one, so image resolution fell back to the
+  pages folder: any image stored in the editor-managed media folder was reported as
+  missing and failed the build. No site could use an image from `media/`.
+
+### Changed
+
+- The folder precedence rules moved into an exported, pure `resolveFolders()`, so an
+  explicit `srcDir` / `mediaDir` in the VitePress config beating the YAML declaration
+  is covered by unit tests instead of only by a running site.
+
+## [0.2.0-rc.1] — 2026-08-05
+
+First published release. Version `0.1.0` existed in-tree only.
+
+### Added
+
+- **Section-type manifest.** The build emits `.cratly/sections.json`, describing the
+  typed properties each container accepts, so the cratly editor can render matching
+  controls. Container declarations in `.cratly.config.yaml` support `props` (with
+  `flags` and `kv` as shorthands) and are merged with Scavold's built-in sections.
+- **Background videos.** The `video` container accepts `overlay` to place the video
+  behind the block's content, plus `controls` to bring the native controls back in
+  that mode.
+- Type declarations for both entry points (`scavold`, `scavold/config`), a `typecheck`
+  script, and the MIT licence text the package always claimed to carry.
+
+### Fixed
+
+- `Scavold.UserConfig` in the shipped declarations was a self-referential type alias
+  (TS2456) and now aliases VitePress's `UserConfig`.
+
+### Known issues
+
+- Flag arguments on the `video` container have no effect: bare words become the
+  container's `class`, while `useVideo()` reads its booleans from `data-*` props, which
+  only `key=value` arguments produce. Use `overlay=1 autoplay=1 loop=1` until this is
+  resolved.
+- Container names that are neither built in nor declared in `.cratly.config.yaml` are
+  not parsed as containers at all, despite `ScavoldContainer` being documented as a
+  catch-all fallback.
+- Only images are processed out of `media_folder`; other file types (video, documents)
+  are never copied into the build output and have to live in the static folder.
+
+[0.2.0-rc.3]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.2...v0.2.0-rc.3
+[0.2.0-rc.2]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.1...v0.2.0-rc.2
+[0.2.0-rc.1]: https://gitlab.com/cepharum-foss/cratly/scavold/-/tags/v0.2.0-rc.1

package/COMPONENTS.md

@@ -495,6 +495,18 @@ Fallback component for Markdown container blocks whose name has no dedicated
 registered component. Renders as the matching HTML sectioning element if the
 container name is one (`section`, `aside`, etc.), otherwise as a `<div>`.
 
+Any container name works without being declared first — undeclared names are caught
+by this component. Because a typo would otherwise become a silent `<div>`, the build
+reports each undeclared name once:
+
+```
+[scavold] container ':::sectoin' is not declared in .cratly.config.yaml — rendering
+it with ScavoldContainer. Declare it to silence this, or fix the name if it is a typo.
+```
+
+Declaring the container in `.cratly.config.yaml` silences the report and gives it
+typed properties in the cratly editor.
+
 Not intended for direct use. Theme developers should instead create a dedicated
 component for each container name they declare in `.cratly.config.yaml`.
 
@@ -697,6 +709,13 @@ All `key=value` pairs from the opening line are passed as additional props with
 `data-` prefix (e.g. `background=/img.jpg` → prop `data-background`). Declare them
 explicitly in `defineProps` to use them.
 
+Flags arrive **both ways**: as part of `class` and as an empty `data-<flag>` prop, so
+a boolean container parameter can be declared as a prop (this is how `useVideo` reads
+`overlay`, `autoplay` and `loop`) while purely presentational flags keep working as
+class names. A flag a component does not declare falls through into the markup as an
+empty attribute — `::: section highlight` renders `<section class="highlight"
+data-highlight>`.
+
 #### Returns
 
 | Name | Type | Description |

package/README.md

@@ -9,11 +9,11 @@ custom containers for Markdown-driven structures on your pages such as galleries
 bun add vitepress vue scavold
 ```
 
-Scavold is currently published as a pre-release, so install it explicitly while
-`latest` does not exist yet:
+Scavold is currently a **pre-release**: breaking changes may occur between releases,
+so pin the version you develop against rather than following the range blindly.
 
 ```sh
-bun add vitepress vue scavold@next
+bun add vitepress vue scavold@^0.2.0-rc.3
 ```
 
 Responsive image generation uses [sharp](https://sharp.pixelplumbing.com/), which

package/lib/config.js

@@ -5,7 +5,7 @@ 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 { extractContainerMediaSrcs, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
 import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
 import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
 
@@ -130,6 +130,35 @@ function parseSizesFromTitle( title ) {
 	return match?.[1] ?? match?.[2] ?? undefined;
 }
 
+/**
+ * Resolves the three content folders from the VitePress config and the declarations
+ * of `.cratly.config.yaml`. An explicit value in the VitePress config always wins,
+ * so a site can express a path in code instead of in the YAML.
+ *
+ * Kept pure and exported so the precedence rules are testable without a filesystem.
+ *
+ * @param {object} rawConfig VitePress user config as passed to augmentConfig()
+ * @param {object} declared folders declared in .cratly.config.yaml (null when absent)
+ * @param {string|null} [declared.pagesFolder] `pages_folder`
+ * @param {string|null} [declared.mediaFolder] `media_folder`
+ * @param {string|null} [declared.staticFolder] `static_folder`
+ * @returns {{srcDir: string|undefined, mediaDir: string|undefined, staticFolder: string|null}}
+ */
+export function resolveFolders( rawConfig = {}, declared = {} ) {
+	const srcDir = rawConfig.srcDir ?? declared.pagesFolder ?? undefined;
+
+	// Media folder for image resolution. Without either source, useMedia() falls back
+	// to srcDir, i.e. images living next to the pages that reference them.
+	const mediaDir = rawConfig.mediaDir ?? declared.mediaFolder ?? 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.
+	// Falls back to "public" at the project root only when srcDir is a subfolder.
+	const staticFolder = declared.staticFolder ?? ( srcDir && srcDir !== "." ? "public" : null );
+
+	return { srcDir, mediaDir, staticFolder };
+}
+
 /**
  * Augments provided VitePress configuration to integrate extended theme
  * features.
@@ -138,42 +167,44 @@ function parseSizesFromTitle( title ) {
  * @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
+ *   declared in .cratly.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;
+	// Read .cratly.config.yaml for structural config and container declarations (Tier 2)
+	let declaredContainers = {};
+	let declaredPagesFolder = null;
+	let declaredMediaFolder = null;
+	let declaredStaticFolder = null;
+	let declaredImageSizes = null;
+	let declaredImageWidths = 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;
+		const cratlyConfig = YAML.parse( raw ) ?? {};
+		declaredContainers = cratlyConfig.containers ?? {};
+		declaredPagesFolder = cratlyConfig.pages_folder ?? null;
+		declaredMediaFolder = cratlyConfig.media_folder ?? null;
+		declaredStaticFolder = cratlyConfig.static_folder ?? null;
+		declaredImageSizes = cratlyConfig.image_sizes ?? null;
+		declaredImageWidths = cratlyConfig.image_widths ?? null;
 	} catch {
 		// file absent or unparseable — proceed with defaults
 	}
 
-	const containerMap = resolveContainerMap( crateContainers, options.containers );
+	const containerMap = resolveContainerMap( declaredContainers, options.containers );
 
-	// Apply srcDir from crate config if not already set in rawConfig
-	const srcDir = rawConfig.srcDir ?? crateSrcDir ?? undefined;
+	// Which container arguments hold a media path — needed twice: to process those
+	// files before rendering, and to rewrite the arguments to their published URL.
+	const mediaProps = mediaPropsOf( buildSectionManifest( declaredContainers, { adapterVersion: SCAVOLD_VERSION } ) );
+
+	const { srcDir, mediaDir, staticFolder } = resolveFolders( rawConfig, {
+		pagesFolder: declaredPagesFolder,
+		mediaFolder: declaredMediaFolder,
+		staticFolder: declaredStaticFolder,
+	} );
 
-	// 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 );
 
@@ -182,6 +213,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	const resolvedConfig = {
 		...rawConfig,
 		...(srcDir !== undefined && { srcDir }),
+		...(mediaDir !== undefined && { mediaDir }),
 		vite: {
 			...rawConfig.vite,
 			...(vitePublicDir !== undefined && { publicDir: vitePublicDir }),
@@ -189,8 +221,8 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	};
 
 	const media = useMedia( resolvedConfig, {
-		...( crateImageSizes != null && { sizes: crateImageSizes } ),
-		...( crateImageWidths != null && { widths: crateImageWidths } ),
+		...( declaredImageSizes != null && { sizes: declaredImageSizes } ),
+		...( declaredImageWidths != null && { widths: declaredImageWidths } ),
 	} );
 
 	async function warmUpMedia() {
@@ -199,7 +231,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		const pageFiles = ( await Array.fromAsync( glob( "**/*.md", { cwd: pagesDir } ) ) )
 			.map( f => join( pagesDir, f ) );
 
-		await media.warmUp( pageFiles );
+		await media.warmUp( pageFiles, source => extractContainerMediaSrcs( source, mediaProps ) );
 	}
 
 	// VitePress's internal markdown LRU cache clear function — not public API
@@ -282,7 +314,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	// at build start and once when the dev server starts listening.
 	async function emitSectionManifest() {
 		try {
-			const manifest = buildSectionManifest( crateContainers, { adapterVersion: SCAVOLD_VERSION } );
+			const manifest = buildSectionManifest( declaredContainers, { adapterVersion: SCAVOLD_VERSION } );
 			await writeSectionManifest( process.cwd(), manifest );
 		} catch ( error ) {
 			console.warn( "[scavold] could not write .cratly/sections.json —", error.message );
@@ -389,7 +421,25 @@ export async function augmentConfig( rawConfig, options = {} ) {
 					return defaultHandler( tokens, idx, options, ...args );
 				} );
 
-				registerContainers( md, containerMap );
+				// A link whose target is a file in the media folder — a PDF an author
+				// uploaded and linked for download, say — points at the path the editor
+				// offers, which is relative to that folder. Rewrite it to the URL the
+				// built site serves. Targets that are not media files (ordinary page
+				// links, anchors, remote URLs) resolve to null and stay untouched.
+				patchRenderer( md, "link_open", ( defaultHandler, tokens, idx, ...args ) => {
+					const published = media.collectAsset( tokens[idx].attrGet( "href" ) );
+
+					if ( published ) {
+						tokens[idx].attrSet( "href", published );
+					}
+
+					return defaultHandler( tokens, idx, ...args );
+				} );
+
+				registerContainers( md, containerMap, {
+					mediaProps,
+					resolveMedia: url => media.collectAsset( url ),
+				} );
 			},
 		},
 	};

package/lib/containers.js

@@ -53,21 +53,41 @@ function resolveTag( name, map ) {
  * @param {string} containerName the original container name from markdown
  * @returns {string}
  */
-function renderToken( tag, token, containerName ) {
+function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia } = {} ) {
 	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( " " );
+	// Arguments declared as `media-file` carry a path relative to the media folder, as
+	// the editor writes them. Turn them into the URL the built site serves.
+	if ( resolveMedia ) {
+		for ( const key of mediaProps[containerName] ?? [] ) {
+			const value = args[key];
 
+			if ( typeof value === "string" ) {
+				args[key] = resolveMedia( value ) ?? value;
+			}
+		}
+	}
+
+	const flags = Object.keys( args ).filter( key => args[key] === true );
+
+	const classes = flags.join( " " );
+
+	// Every argument is emitted as a data-* attribute, flags included — a flag is a
+	// boolean parameter of the container, and a component declaring it as a prop
+	// (see useVideo) has to be able to receive it. Flags additionally stay classes,
+	// which is what purely presentational ones like `dark` or `centered` are used for.
+	// A component that declares the prop consumes the attribute; one that does not
+	// lets it fall through into the markup.
 	const attrs = Object.entries( args )
 		.filter( ( [ , value ] ) => value && value !== true )
 		.map( ( [ key, value ] ) => `data-${key}="${value}"` );
 
+	attrs.push( ...flags.map( flag => `data-${flag}=""` ) );
+
 	attrs.push( `data-container="${containerName}"` );
 
 	if ( classes ) {
@@ -80,36 +100,85 @@ function renderToken( tag, token, containerName ) {
 /**
  * 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.
+ * not in the map. Undeclared names are reported once each, so a typo does not
+ * silently turn into a `<div>`.
  *
  * @param {import('markdown-it')} md markdown-it instance
  * @param {Object<string,string>} containerMap resolved name→component map
+ * @param {object} [options]
+ * @param {function} [options.warn] sink for the undeclared-name reports
  */
-export function registerContainers( md, containerMap ) {
+export function registerContainers( md, containerMap, { warn = console.warn, mediaProps, resolveMedia } = {} ) {
+	const renderOptions = { mediaProps, resolveMedia };
+
 	for ( const [ name, tag ] of Object.entries( containerMap ) ) {
 		md.use( ContainerPlugin, name, {
-			render: ( tokens, index ) => renderToken( tag, tokens[index], name ),
+			render: ( tokens, index ) => renderToken( tag, tokens[index], name, renderOptions ),
 		} );
 	}
+
+	// Catch-all, registered last so every known name is matched by its own rule
+	// first. Without it an undeclared name is not a container at all and its fences
+	// end up as literal text in the page.
+	const reported = new Set();
+
+	md.use( ContainerPlugin, "scavold-unknown", {
+		validate: params => {
+			const name = containerNameOf( params );
+
+			return Boolean( name ) && !( name in containerMap );
+		},
+		render: ( tokens, index ) => {
+			const name = containerNameOf( tokens[index].info );
+
+			// A typo would otherwise become a silent <div> — the fences used to stay
+			// visible in the page, which was crude but at least noticeable. Report each
+			// unknown name once per build; declaring it in .cratly.config.yaml silences
+			// this and gives it typed properties in the editor.
+			if ( tokens[index].nesting === 1 && !reported.has( name ) ) {
+				reported.add( name );
+				warn(
+					"[scavold] container ':::%s' is not declared in .cratly.config.yaml — " +
+					"rendering it with ScavoldContainer. Declare it to silence this, or fix the name if it is a typo.",
+					name
+				);
+			}
+
+			return renderToken( resolveTag( name, containerMap ), tokens[index], name, renderOptions );
+		},
+	} );
+}
+
+/**
+ * Extracts the container name from a container fence's info string, i.e. the first
+ * word after the colons. Returns an empty string when it is not a usable name.
+ *
+ * @param {string} params info string of the opening fence, e.g. "teaser dark x=1"
+ * @returns {string}
+ */
+function containerNameOf( params ) {
+	const [ name = "" ] = String( params ).trim().split( /\s+/, 1 );
+
+	return /^[a-z][\w-]*$/i.test( name ) ? name : "";
 }
 
 /**
  * Merges the Scavold default container map with site-level declarations from
- * .crate.config.yaml and an explicit developer-supplied override map.
+ * .cratly.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})
+ *   2. Names declared in the containers block of .cratly.config.yaml (mapped to Scavold{Name})
  *   3. Explicit overrides passed directly to augmentConfig
  *
- * @param {object} [crateContainers] containers block from .crate.config.yaml
+ * @param {object} [declaredContainers] containers block from .cratly.config.yaml
  * @param {Object<string,string>} [overrides] explicit name→component overrides
  * @returns {Object<string,string>}
  */
-export function resolveContainerMap( crateContainers = {}, overrides = {} ) {
+export function resolveContainerMap( declaredContainers = {}, overrides = {} ) {
 	const map = defaultContainerMap();
 
-	for ( const [ name, value ] of Object.entries( crateContainers ) ) {
+	for ( const [ name, value ] of Object.entries( declaredContainers ) ) {
 		if ( typeof value === "string" ) {
 			// shorthand: "name: ComponentName" — treat string as explicit component override
 			map[name] = value;
@@ -126,3 +195,64 @@ export function resolveContainerMap( crateContainers = {}, overrides = {} ) {
 
 	return map;
 }
+
+/**
+ * Collects the values of container arguments declared as `media-file`, so the media
+ * pipeline can process them before rendering. Markdown syntax does not reveal these
+ * references — `:::video src=/clip.mp4` is a fence, not an image — which is why they
+ * need their own extraction pass.
+ *
+ * @param {string} source markdown source of one page
+ * @param {Object<string,string[]>} mediaProps container name → names of its media-file props
+ * @returns {string[]} referenced media paths, as written by the author
+ */
+export function extractContainerMediaSrcs( source, mediaProps = {} ) {
+	const srcs = [];
+
+	for ( const line of String( source ).split( /\r?\n/ ) ) {
+		const match = /^:{3,}\s*(\S+)(.*)$/.exec( line );
+
+		if ( !match ) {
+			continue;
+		}
+
+		const keys = mediaProps[match[1]];
+
+		if ( !keys?.length ) {
+			continue;
+		}
+
+		const args = parseKeyValuePairs( match[2].trim() );
+
+		for ( const key of keys ) {
+			if ( typeof args[key] === "string" ) {
+				srcs.push( args[key] );
+			}
+		}
+	}
+
+	return srcs;
+}
+
+/**
+ * Derives the media-file argument names per container from a section-type manifest,
+ * covering both Scavold's built-in containers and the site's own declarations.
+ *
+ * @param {{sections?: Object<string,{props?: Object<string,{type?: string}>}>}} manifest
+ * @returns {Object<string,string[]>} container name → names of its media-file props
+ */
+export function mediaPropsOf( manifest ) {
+	const map = {};
+
+	for ( const [ name, section ] of Object.entries( manifest?.sections ?? {} ) ) {
+		const keys = Object.entries( section?.props ?? {} )
+			.filter( ( [ , def ] ) => def?.type === "media-file" )
+			.map( ( [ key ] ) => key );
+
+		if ( keys.length ) {
+			map[name] = keys;
+		}
+	}
+
+	return map;
+}

package/lib/media.js

@@ -1,11 +1,28 @@
 import { createHash } from "node:crypto";
-import { join, basename, extname } from "node:path";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join, basename, dirname, extname } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import sharp from "sharp";
 
 const DEFAULT_WIDTHS = [ 320, 640, 960, 1280, 1920 ];
 
+/**
+ * File types the image pipeline can scale. Everything else in the media folder is
+ * published by copying it verbatim — authors upload PDFs, videos and other downloads
+ * into the same folder, and the editor offers them for reference just like images.
+ */
+const IMAGE_EXTENSIONS = new Set( [ "jpg", "jpeg", "png", "webp", "avif", "gif", "tiff" ] );
+
+/**
+ * Decides whether a media file goes through the image pipeline.
+ *
+ * @param {string} filePath path or URL of the media file
+ * @returns {boolean}
+ */
+export function isProcessableImage( filePath ) {
+	return IMAGE_EXTENSIONS.has( extname( filePath ).toLowerCase().replace( ".", "" ) );
+}
+
 /**
  * Returns the public output folder for generated image variants.
  *
@@ -111,6 +128,26 @@ export function extractImageSrcs( source ) {
 	return srcs;
 }
 
+/**
+ * Extracts local link targets from a markdown source string, skipping image syntax.
+ * Most of these are ordinary page links; the media pipeline treats them as optional
+ * candidates and ignores the ones that do not resolve to a file in the media folder.
+ *
+ * @param {string} source markdown source
+ * @returns {string[]} list of link targets found
+ */
+export function extractLinkTargets( source ) {
+	const targets = [];
+
+	for ( const match of source.matchAll( /(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g ) ) {
+		if ( match[1] !== "!" ) {
+			targets.push( match[2] );
+		}
+	}
+
+	return targets;
+}
+
 /**
  * Sets up media handling for a Scavold-based VitePress site.
  *
@@ -134,6 +171,9 @@ export function useMedia( config, options = {} ) {
 	/** @type {Map<string, {src: string, srcset: string, webpSrcset: string, sizes: string}>} */
 	const cache = new Map();
 
+	/** Published URL per non-image media reference, e.g. "/handbook.pdf" → "/media/handbook.pdf". */
+	const assets = new Map();
+
 	/**
 	 * Resolves a markdown image src to an absolute filesystem path, or null for
 	 * remote URLs.
@@ -157,8 +197,8 @@ export function useMedia( config, options = {} ) {
 	 * @param {string} imageUrl
 	 * @returns {Promise<void>}
 	 */
-	async function process( imageUrl ) {
-		if ( cache.has( imageUrl ) ) {
+	async function process( imageUrl, { optional = false } = {} ) {
+		if ( cache.has( imageUrl ) || assets.has( imageUrl ) ) {
 			return;
 		}
 
@@ -169,7 +209,26 @@ export function useMedia( config, options = {} ) {
 		}
 
 		if ( !existsSync( filePath ) ) {
-			console.error( "image %s is missing (resolved to %s)", imageUrl, filePath );
+			// Optional candidates are link targets: most links point at pages, not at
+			// media, so a miss is the normal case and not worth reporting.
+			if ( !optional ) {
+				console.error( "media file %s is missing (resolved to %s)", imageUrl, filePath );
+			}
+
+			return;
+		}
+
+		// Anything the image pipeline cannot scale — PDFs, videos, archives — is
+		// published by copying it into the same output folder, keeping its path so the
+		// reference the editor offers stays valid.
+		if ( !isProcessableImage( filePath ) ) {
+			const relative = imageUrl.replace( /^\//, "" );
+			const target = join( outDir, relative );
+
+			mkdirSync( dirname( target ), { recursive: true } );
+			copyFileSync( filePath, target );
+			assets.set( imageUrl, `/media/${relative}` );
+
 			return;
 		}
 
@@ -190,10 +249,14 @@ export function useMedia( config, options = {} ) {
 		 * Call this from the VitePress buildStart hook.
 		 *
 		 * @param {string[]} pageFiles absolute paths to markdown source files
+		 * @param {function(string): string[]} [extraSrcs] returns further media references
+		 *        found in a page source — used for container arguments declared as
+		 *        `media-file`, which markdown syntax does not reveal
 		 * @returns {Promise<void>}
 		 */
-		async warmUp( pageFiles ) {
+		async warmUp( pageFiles, extraSrcs = () => [] ) {
 			const srcs = new Set();
+			const candidates = new Set();
 
 			await Promise.all( pageFiles.map( async file => {
 				const source = await readFile( file, "utf-8" );
@@ -201,9 +264,20 @@ export function useMedia( config, options = {} ) {
 				for ( const src of extractImageSrcs( source ) ) {
 					srcs.add( src );
 				}
+
+				for ( const src of extraSrcs( source ) ) {
+					srcs.add( src );
+				}
+
+				for ( const target of extractLinkTargets( source ) ) {
+					candidates.add( target );
+				}
 			} ) );
 
-			await Promise.all( [ ...srcs ].map( src => process( src ) ) );
+			await Promise.all( [
+				...[ ...srcs ].map( src => process( src ) ),
+				...[ ...candidates ].filter( t => !srcs.has( t ) ).map( t => process( t, { optional: true } ) ),
+			] );
 		},
 
 		/**
@@ -227,5 +301,21 @@ export function useMedia( config, options = {} ) {
 
 			return data;
 		},
+
+		/**
+		 * Returns the published URL for any media reference — the copied file for
+		 * non-images, the fallback variant for images. Used where a single URL is
+		 * needed rather than a srcset: markdown links, and container arguments
+		 * declared as `media-file` such as a video's `src` or `poster`.
+		 *
+		 * Returns null for references that are not media files, so callers can leave
+		 * ordinary links and remote URLs untouched. Must be called after warmUp().
+		 *
+		 * @param {string} url reference as written by the author, resolved against the media folder
+		 * @returns {string|null}
+		 */
+		collectAsset( url ) {
+			return assets.get( url ) ?? cache.get( url )?.src ?? null;
+		},
 	};
 }

package/lib/sectionManifest.js

@@ -120,19 +120,19 @@ function propsFromDeclaration( decl ) {
  * `containers` declarations from .cratly.config.yaml — adding custom sections
  * and overriding labels/hints/props of built-ins.
  *
- * @param {object} [crateContainers] the `containers` block from .cratly.config.yaml
+ * @param {object} [declaredContainers] the `containers` block from .cratly.config.yaml
  * @param {object} [options]
  * @param {string} [options.adapterVersion] version reported under `adapter.version`
  * @returns {object} manifest conforming to SECTION_SCHEMA_URL
  */
-export function buildSectionManifest( crateContainers = {}, { adapterVersion } = {} ) {
+export function buildSectionManifest( declaredContainers = {}, { adapterVersion } = {} ) {
 	const sections = {};
 
 	for ( const [ name, def ] of Object.entries( BUILTIN_SECTIONS ) ) {
 		sections[name] = structuredClone( def );
 	}
 
-	for ( const [ name, value ] of Object.entries( crateContainers ) ) {
+	for ( const [ name, value ] of Object.entries( declaredContainers ) ) {
 		const decl = typeof value === "string" || value == null ? {} : value;
 		const entry = sections[name] ?? {};
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.1",
+	"version": "0.2.0-rc.3",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [
@@ -49,6 +49,7 @@
 		"lib",
 		"scripts",
 		"index.d.ts",
+		"CHANGELOG.md",
 		"COMPONENTS.md",
 		"FRONTMATTER.md",
 		"README.md",