scavold 0.2.0-rc.10 → 0.2.0-rc.12

package/CHANGELOG.md

@@ -9,6 +9,25 @@ changes may occur in any release.
 
 ## [Unreleased]
 
+## [0.2.0-rc.12] — 2026-10-03
+
+### Added
+
+- `:::cover` takes `tone=light` or `tone=dark` for content on top that is meant to be
+  light or dark, depending on the picture. It only marks the cover with
+  `scavold-cover--light` or `scavold-cover--dark`; the colours are the theme's. The
+  editor offers it as a choice.
+
+## [0.2.0-rc.11] — 2026-10-01
+
+### Added
+
+- A container opening a page carries an empty `data-leading` attribute, and the page
+  data name it as `leadingContainer` — known before the content renders, so a layout
+  can arrange its own parts around a cover at the top of a page, e.g. move its
+  breadcrumb below it. Both are information only; nothing changes for a theme that
+  does not ask.
+
 ## [0.2.0-rc.10] — 2026-10-01
 
 ### Added
@@ -324,7 +343,9 @@ First published release. Version `0.1.0` existed in-tree only.
 - 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.
 
-[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.10...main
+[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.12...main
+[0.2.0-rc.12]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.11...v0.2.0-rc.12
+[0.2.0-rc.11]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.10...v0.2.0-rc.11
 [0.2.0-rc.10]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.9...v0.2.0-rc.10
 [0.2.0-rc.9]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.8...v0.2.0-rc.9
 [0.2.0-rc.8]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.7...v0.2.0-rc.8

package/COMPONENTS.md

@@ -451,12 +451,13 @@ the window, cropped to fit — a cover, or hero, at the top of a page. Written a
 | `poster` | `media-file` | — | Only for a video: still image shown until it plays, and instead of playing for visitors who asked for reduced motion. |
 | `focus` | `string` | `50% 50%` | Part of the picture kept visible when the window crops it, as a CSS `object-position` — `center top`, `30% 60%`. |
 | `label` | `string` | — | Alternative text of an image, accessible label of a video. Left out, the picture is treated as decoration. |
+| `tone` | `"light" \| "dark"` | — | Whether the content on top is meant to be light (over a dark picture) or dark (over a bright one). Only marks the cover with `scavold-cover--light` or `scavold-cover--dark`; what that looks like is the theme's. Left out, or with any other value, the cover carries neither class. |
 
 #### Rendered markup
 
 ```html
-<!-- image -->
-<div class="scavold-cover" style="--scavold-cover-focus: center top">
+<!-- image, tone=light -->
+<div class="scavold-cover scavold-cover--light" style="--scavold-cover-focus: center top">
   <picture class="scavold-cover__media">
     <source type="image/webp" srcset="..." sizes="(min-aspect-ratio: 2400/1350) 100vw, 177.78vh" />
     <source srcset="..." sizes="..." />
@@ -504,6 +505,80 @@ html { overflow-x: clip; }
 The overlay is an empty grid cell over the picture; position its content, add a scrim
 for legibility and restyle `.scavold-cover__toggle` as the design asks.
 
+The `tone` an author picked is the theme's to honour. Scavold sets no colour for it;
+a theme gives each tone the colours of its design, including headings and links its
+prose styles colour on their own:
+
+```css
+.scavold-cover--light .scavold-cover__overlay { color: #fff; }
+.scavold-cover--dark .scavold-cover__overlay { color: #000; }
+```
+
+#### A cover opening the page
+
+Where the theme's own parts go around a cover is the theme's choice; Scavold places
+none of them. It only tells, in two ways, that a page opens with a container:
+
+- the container carries an empty `data-leading` attribute;
+- the page data carry `leadingContainer`, the name of that container (`"cover"`), or
+  `null` when the page opens with anything else. A layout renders its own parts before
+  the page content, so this is known at build time, ahead of the content.
+
+A theme that wants its breadcrumb below a cover opening the page, rather than above
+it, combines both. The layout leaves out the breadcrumb on such a page:
+
+```vue
+<!-- Layout.vue -->
+<script setup>
+import { useData } from "vitepress";
+const { page } = useData();
+</script>
+
+<template>
+  <ScavoldBreadcrumb v-if="page.leadingContainer !== 'cover'" />
+  <Content />
+</template>
+```
+
+…and the cover is mapped to a component of the site's own that wraps the built-in one
+and adds the breadcrumb after it when it is the leading one:
+
+```yaml
+# .cratly.config.yaml — the editor keeps offering the cover's own properties
+containers:
+  cover:
+    component: SiteCover
+```
+
+```vue
+<!-- .vitepress/theme/components/SiteCover.vue -->
+<script setup>
+import ScavoldCover from "scavold/components/ScavoldCover.vue";
+import ScavoldBreadcrumb from "scavold/components/ScavoldBreadcrumb.vue";
+
+defineOptions( { inheritAttrs: false } );
+</script>
+
+<template>
+  <ScavoldCover v-bind="$attrs"><slot /></ScavoldCover>
+  <ScavoldBreadcrumb v-if="$attrs['data-leading'] != null" />
+</template>
+```
+
+```js
+// .vitepress/theme/index.js — the container renders the component by name
+async function enhanceApp( context ) {
+    await scavoldEnhanceApp( context );
+    context.app.component( "SiteCover", SiteCover );
+}
+```
+
+Below a cover the breadcrumb sits inside the content column, so the theme's prose
+styles reach its list; keep them out where they differ from the breadcrumb's own.
+
+Visual and reading order stay the same this way, which a reordering stylesheet could
+not promise.
+
 ---
 
 ### `<ScavoldPageList>`
@@ -861,12 +936,13 @@ renders the same picture the way its design asks:
 
 ```js
 const props = defineProps( { ...coverProps } );
-const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label } = useCover( props );
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
 ```
 
 `srcset`, `webpSrcset` and `sizes` are filled for an image only; the build provides
-the variants and the dimensions `sizes` is derived from. `isVideoUrl( url )` and
-`coverSizes( width, height )` are exported as well.
+the variants and the dimensions `sizes` is derived from. `tone` is `"light"`, `"dark"`
+or empty, one of `COVER_TONES`. `isVideoUrl( url )` and `coverSizes( width, height )`
+are exported as well.
 
 ---
 
@@ -1040,6 +1116,12 @@ class names. A flag a component does not declare falls through into the markup a
 empty attribute — `::: section highlight` renders `<section class="highlight"
 data-highlight>`.
 
+A container that opens the page — its fence is the first thing in the page body —
+additionally receives an empty `data-leading` attribute. It is information only and
+changes nothing by itself; a component or a stylesheet can tell from it that this
+block stands at the very top. The same fact reaches the layout ahead of the content as
+`page.leadingContainer` (see [A cover opening the page](#a-cover-opening-the-page)).
+
 #### Returns
 
 | Name | Type | Description |

package/components/ScavoldCover.vue

@@ -7,7 +7,7 @@ import ScavoldImage from "./ScavoldImage.vue";
 
 const props = defineProps( coverProps );
 
-const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label } = useCover( props );
+const { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone } = useCover( props );
 
 const { t } = useScavoldI18n();
 const playLabel = t( "cover.play" );
@@ -46,7 +46,7 @@ function toggle() {
   <div
     v-if="src"
     class="scavold-cover"
-    :class="{ 'scavold-cover--video': isVideo }"
+    :class="[ { 'scavold-cover--video': isVideo }, tone && `scavold-cover--${tone}` ]"
     :style="style"
   >
     <video

package/composables/useCover.js

@@ -39,8 +39,17 @@ export const coverProps = {
 
 	/** Alternative text of an image, accessible label of a video. */
 	dataLabel: { type: String, default: "" },
+
+	/** Whether the content on top is meant to be light or dark, see COVER_TONES. */
+	dataTone: { type: String, default: "" },
 };
 
+/**
+ * Tones an author may ask the content on top of a cover to take. The cover only
+ * marks its choice; the theme decides what light or dark content looks like.
+ */
+export const COVER_TONES = [ "light", "dark" ];
+
 /**
  * Tells whether a URL names a video by its file extension.
  *
@@ -91,9 +100,10 @@ export function coverSizes( width, height ) {
  *   - `poster`     — still image of a video, or empty string
  *   - `focus`      — CSS `object-position` value, or empty string
  *   - `label`      — alternative text or accessible label, or empty string
+ *   - `tone`       — `"light"` or `"dark"` for the content on top, or empty string
  *
  * @param {object} props reactive props from defineProps
- * @returns {{ src, isVideo, srcset, webpSrcset, sizes, poster, focus, label }}
+ * @returns {{ src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone }}
  */
 export function useCover( props ) {
 	const src = computed( () => props.dataSrc ?? "" );
@@ -107,5 +117,12 @@ export function useCover( props ) {
 	const focus = computed( () => props.dataFocus ?? "" );
 	const label = computed( () => props.dataLabel ?? "" );
 
-	return { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label };
+	// Anything but a known tone leaves the choice to the theme.
+	const tone = computed( () => {
+		const value = String( props.dataTone ?? "" ).trim().toLowerCase();
+
+		return COVER_TONES.includes( value ) ? value : "";
+	} );
+
+	return { src, isVideo, srcset, webpSrcset, sizes, poster, focus, label, tone };
 }

package/index.d.ts

@@ -37,6 +37,9 @@ export module Scavold {
 
 	interface AugmentedPageData extends PageData {
 		hierarchy: HierarchyNode;
+
+		/** Name of the container the page opens with, e.g. `"cover"`, or null when it opens with anything else. Known before the content renders, so a layout can arrange its own parts around it. */
+		leadingContainer: string | null;
 	}
 
 	interface MenuItem {

package/lib/config.js

@@ -8,7 +8,7 @@ import { extractFrontmatterMediaSrcs } from "./excerpt.js";
 import { DEFAULT_FEED_LIMIT, collectFeedPages, renderRss } from "./feed.js";
 import { useMedia } from "./media.js";
 import { patchRenderer } from "./markdown.js";
-import { extractContainerMediaSrcs, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
+import { extractContainerMediaSrcs, leadingContainerOf, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
 import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
 import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
 import { assertUniquePageKeys } from "./pageKeys.js";
@@ -686,7 +686,21 @@ export async function augmentConfig( rawConfig, options = {} ) {
 				url => media.collectImage( url ),
 			);
 
-			return { hierarchy };
+			// A layout renders its own parts — a breadcrumb, say — before the page
+			// content, so whether the page opens with a container has to be known before
+			// that content is rendered. Read from the source rather than the rendered
+			// page, which does not exist yet when the layout needs it.
+			let leadingContainer = null;
+
+			try {
+				leadingContainer = leadingContainerOf(
+					readFileSync( join( sourceFolder( resolvedConfig ), pageData.filePath ), "utf-8" ),
+				);
+			} catch {
+				// a page without a source file of its own, e.g. a generated one
+			}
+
+			return { hierarchy, leadingContainer };
 		},
 		markdown: {
 			config( md ) {

package/lib/containers.js

@@ -55,7 +55,7 @@ function resolveTag( name, map ) {
  * @param {string} containerName the original container name from markdown
  * @returns {string}
  */
-function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia, resolveImage } = {} ) {
+function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia, resolveImage } = {}, leading = false ) {
 	if ( token.nesting !== 1 ) {
 		return `</${tag}>\n`;
 	}
@@ -107,6 +107,13 @@ function renderToken( tag, token, containerName, { mediaProps = {}, resolveMedia
 
 	attrs.push( `data-container="${containerName}"` );
 
+	// A container opening the page is marked as such, so a theme can tell a cover at
+	// the top of a page from one further down. It is information only; see
+	// leadingContainerOf() for the page-level counterpart.
+	if ( leading ) {
+		attrs.push( 'data-leading=""' );
+	}
+
 	if ( classes ) {
 		attrs.push( `class="${classes}"` );
 	}
@@ -133,7 +140,7 @@ export function registerContainers( md, containerMap, { warn = console.warn, med
 
 	for ( const [ name, tag ] of Object.entries( containerMap ) ) {
 		md.use( ContainerPlugin, name, {
-			render: ( tokens, index ) => renderToken( tag, tokens[index], name, renderOptions ),
+			render: ( tokens, index ) => renderToken( tag, tokens[index], name, renderOptions, index === 0 ),
 		} );
 	}
 
@@ -164,11 +171,31 @@ export function registerContainers( md, containerMap, { warn = console.warn, med
 				);
 			}
 
-			return renderToken( resolveTag( name, containerMap ), tokens[index], name, renderOptions );
+			return renderToken( resolveTag( name, containerMap ), tokens[index], name, renderOptions, index === 0 );
 		},
 	} );
 }
 
+/**
+ * Names the container a page opens with, i.e. the one whose fence is the first thing
+ * in the page body, or null when the page opens with anything else. Follows
+ * markdown-it: the front matter does not count, blank lines do not either, and a
+ * fence may be indented by up to three spaces.
+ *
+ * This is the page-level counterpart of the `data-leading` attribute: a layout
+ * renders its own parts before the page content, so it has to know in advance.
+ *
+ * @param {string} source markdown source of one page, front matter included
+ * @returns {string|null}
+ */
+export function leadingContainerOf( source ) {
+	const body = String( source ?? "" ).replace( /^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/, "" );
+	const first = body.split( /\r?\n/ ).find( line => line.trim() !== "" ) ?? "";
+	const match = /^ {0,3}:{3,}\s*(.*)$/.exec( first );
+
+	return match ? containerNameOf( match[1] ) || null : null;
+}
+
 /**
  * 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.

package/lib/sectionManifest.js

@@ -88,6 +88,12 @@ export const BUILTIN_SECTIONS = {
 				label: "Description",
 				hint: "Alternative text of the image, or what the video shows. Leave empty when it is decoration only.",
 			},
+			tone: {
+				type: "enum",
+				label: "Content on top",
+				values: [ "light", "dark" ],
+				hint: "\"light\" over a dark picture, \"dark\" over a bright one. Left unset, the site's design decides.",
+			},
 		},
 	},
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.10",
+	"version": "0.2.0-rc.12",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [

package/scripts/check-fixture.js

@@ -297,6 +297,12 @@ const covers = cover.split( /<div class="scavold-cover[ "]/ ).slice( 1 );
 const [ coverImage = "", coverVideo = "" ] = covers;
 
 expect( covers.length === 2, "renders both covers of the page", `found ${covers.length}` );
+expect( /<div class="scavold-cover[ "][^>]*\sdata-leading[\s=>]/.test( cover ) && cover.match( /\sdata-leading[\s=>]/g )?.length === 1,
+	"marks the cover opening the page, and only that one" );
+expect( cover.includes( '<main data-leading-container="cover">' ),
+	"tells the layout before the content renders that the page opens with a cover" );
+expect( !/<main[^>]*data-leading-container/.test( built( "media.html" ) ),
+	"tells it nothing on a page that opens with anything else" );
 // The variants, not just the widest one: a cover is the largest image of a page and
 // must not cost a phone the full 1920px file.
 expect( /<source type="image\/webp" srcset="[^"]*wide--320w-[0-9a-f]+\.webp 320w[^"]*wide--1920w-[0-9a-f]+\.webp 1920w"/.test( coverImage ),
@@ -315,6 +321,9 @@ expect( /class="scavold-cover__overlay"[^>]*>\s*(?:<!--\[-->)?\s*<h1[^>]*>Over t
 const coverVideoTag = tags( coverVideo, "video" )[0] ?? "";
 
 expect( coverVideo.startsWith( "scavold-cover--video" ), "tells a video cover by its file type" );
+// A mark for the theme to style, nothing more.
+expect( /^scavold-cover--light"/.test( coverImage ), "marks the tone asked for the content on top" );
+expect( !/scavold-cover--(light|dark)/.test( coverVideo ), "marks no tone where none is asked for" );
 expect( !cover.includes( "data-poster-srcset" ), "keeps the variants of a still image out of the markup" );
 expect( /src="\/media\/clip\.mp4"/.test( coverVideoTag ) && /poster="\/media\/wide--\d+w-[0-9a-f]+\.jpg"/.test( coverVideoTag ),
 	"resolves a cover video and its still image to their published URLs" );