scavold 0.2.0-rc.10 → 0.2.0-rc.11

package/CHANGELOG.md

@@ -9,6 +9,16 @@ changes may occur in any release.
 
 ## [Unreleased]
 
+## [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 +334,8 @@ 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.11...main
+[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

@@ -504,6 +504,71 @@ 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.
 
+#### 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>`
@@ -1040,6 +1105,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/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/package.json

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