scavold 0.2.0-rc.1 → 0.2.0-rc.2

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# 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.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.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/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.2
 ```
 
 Responsive image generation uses [sharp](https://sharp.pixelplumbing.com/), which

package/lib/config.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.
@@ -144,6 +173,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	// Read .crate.config.yaml for structural config and container declarations (Tier 2)
 	let crateContainers = {};
 	let crateSrcDir = null;
+	let crateMediaDir = null;
 	let crateStaticDir = null;
 	let crateImageSizes = null;
 	let crateImageWidths = null;
@@ -155,6 +185,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		const crate = YAML.parse( raw ) ?? {};
 		crateContainers = crate.containers ?? {};
 		crateSrcDir = crate.pages_folder ?? null;
+		crateMediaDir = crate.media_folder ?? null;
 		crateStaticDir = crate.static_folder ?? null;
 		crateImageSizes = crate.image_sizes ?? null;
 		crateImageWidths = crate.image_widths ?? null;
@@ -164,16 +195,12 @@ export async function augmentConfig( rawConfig, options = {} ) {
 
 	const containerMap = resolveContainerMap( crateContainers, options.containers );
 
-	// Apply srcDir from crate config if not already set in rawConfig
-	const srcDir = rawConfig.srcDir ?? crateSrcDir ?? undefined;
+	const { srcDir, mediaDir, staticFolder } = resolveFolders( rawConfig, {
+		pagesFolder: crateSrcDir,
+		mediaFolder: crateMediaDir,
+		staticFolder: crateStaticDir,
+	} );
 
-	// 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 +209,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 	const resolvedConfig = {
 		...rawConfig,
 		...(srcDir !== undefined && { srcDir }),
+		...(mediaDir !== undefined && { mediaDir }),
 		vite: {
 			...rawConfig.vite,
 			...(vitePublicDir !== undefined && { publicDir: vitePublicDir }),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.1",
+	"version": "0.2.0-rc.2",
 	"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",