scavold 0.2.0-rc.1

package/FRONTMATTER.md

@@ -0,0 +1,248 @@
+# Scavold front matter reference
+
+Front matter is YAML declared at the top of a Markdown file between `---` fences.
+Scavold reads a set of well-known keys from every page's front matter at build time
+to drive navigation, localisation, redirects, and URL aliasing. All keys are
+optional unless noted otherwise.
+
+```yaml
+---
+title: My page title
+label: Short label
+order: 10
+locale: de
+---
+```
+
+---
+
+## `title`
+
+**Type:** `string`
+
+The display title for the page. Used in menus and breadcrumbs when no `label` is
+set, and exposed as `node.title` on the hierarchy node.
+
+When absent, Scavold falls back to the first `#` heading found in the page
+body, then to the path segment if no heading exists either.
+
+```yaml
+---
+title: Datenschutzerklärung
+---
+```
+
+---
+
+## `label`
+
+**Type:** `string`
+
+A short navigation label used in menus and breadcrumbs in place of `title`. Useful
+when the full page title is too long for a navigation item.
+
+When absent, menus fall back to `title`, then to the path segment.
+
+```yaml
+---
+title: Allgemeine Geschäftsbedingungen
+label: AGB
+---
+```
+
+---
+
+## `order`
+
+**Type:** `number`
+
+Controls the position of this page among its siblings in the hierarchy. Pages are
+sorted by `order` ascending; pages without an `order` value follow in filename order
+after all ordered pages.
+
+Using multiples of 10 leaves room to insert pages later without renumbering
+existing ones.
+
+```yaml
+---
+order: 20
+---
+```
+
+A section with mixed ordered and unordered pages:
+
+```
+10  → kontakt.md
+20  → leistungen/
+    (no order) → agb.md        # follows after ordered pages, a–z
+    (no order) → impressum.md
+```
+
+---
+
+## `url`
+
+**Type:** `string`
+
+Overrides the public URL of the page. VitePress builds the page at this path
+instead of the URL derived from the source file location. The source path never
+appears in the browser's address bar.
+
+The value is a root-relative path without a leading slash. The `.md` extension is
+optional. Index-style paths (`de/impressum/`) are also accepted.
+
+```yaml
+---
+url: de/impressum
+---
+```
+
+For example, a page whose source lives under a `footer/` section would normally be
+reachable at `/de/footer/impressum`. With the declaration above its URL becomes
+`/de/impressum` — the `/footer/` segment is invisible to visitors.
+
+Menu links and breadcrumbs produced by Scavold automatically use the alias URL.
+
+**Conflict detection:** if two pages declare the same `url` value, the build aborts
+with an error naming both conflicting files. Each alias must be unique across the
+entire site.
+
+---
+
+## `locale` / `lang`
+
+**Type:** `string` (BCP 47 language tag, e.g. `de`, `en`, `fr-CH`)
+
+Declares the language of this page. The value is inherited by all pages in the same
+section — setting it once on a section's `index.md` is enough for the whole
+subtree. Individual pages can override the inherited value.
+
+`locale` is the preferred key. `lang` is accepted as an alias for backwards
+compatibility; when both are present, `locale` takes precedence.
+
+```yaml
+---
+locale: de
+---
+```
+
+Scavold uses the resolved locale to:
+
+- drive the locale switcher (`ScavoldLocaleMenu`)
+- select the correct branch in locale-conditional redirects
+- resolve `{locale}` placeholders in `ScavoldMenu`'s `from-path` prop
+
+---
+
+## `translations`
+
+**Type:** `object` — map of BCP 47 locale code → relative page path
+
+Declares counterpart pages in other locales. Used by `ScavoldLocaleMenu` to offer
+direct links to the same content in a different language.
+
+```yaml
+---
+translations:
+  en: en/about.md
+  fr: fr/a-propos.md
+---
+```
+
+Paths are relative to the project's pages folder. The `.md` extension is required.
+
+**Automatic back-links:** when page A declares `translations.en: en/about.md`,
+Scavold automatically adds the reverse entry (`translations.de: de/ueber-uns.md`)
+to `en/about.md` at build time — provided that page has no explicit `translations`
+entry for that locale already. This means you only need to declare the link on one
+side.
+
+If an explicit back-link on the target page points to a *different* page, Scavold
+emits a warning and the explicit declaration takes precedence.
+
+---
+
+## `hide`
+
+**Type:** `boolean | "menu" | "breadcrumb"`
+
+Controls whether this page appears in menus, breadcrumbs, or both.
+
+| Value | Effect |
+|---|---|
+| `false` or absent | Visible everywhere (default) |
+| `true` | Hidden in both menus and breadcrumbs |
+| `"menu"` | Hidden in menus only |
+| `"breadcrumb"` | Hidden in breadcrumbs only |
+
+```yaml
+---
+hide: true
+---
+```
+
+```yaml
+---
+hide: menu
+---
+```
+
+Pages hidden from menus are still reachable by direct URL and still appear as nodes
+in the hierarchy tree — they are only excluded from rendered navigation.
+
+---
+
+## `redirect`
+
+**Type:** `string | object`
+
+Declares a redirect from this page to another URL. Two forms are supported:
+unconditional and locale-conditional.
+
+### Unconditional redirect
+
+A plain string value, or an object with only a `"*"` key, redirects all visitors
+regardless of locale. The redirect is compiled into VitePress `rewrites` at build
+time and handled server-side — the original URL is never served to the browser.
+
+```yaml
+---
+redirect: other-page.md
+---
+```
+
+```yaml
+---
+redirect:
+  "*": other-page.md
+---
+```
+
+Paths are resolved relative to the current page's location.
+
+### Locale-conditional redirect
+
+An object with locale keys routes visitors to different pages depending on the
+language preferences reported by their browser (`navigator.languages`). This is
+handled client-side on first render.
+
+```yaml
+---
+redirect:
+  de: /de/
+  en: /en/
+  "*": /en/
+---
+```
+
+Scavold matches the browser's preferred languages against the map keys in order and
+calls `location.replace()` on the first match, replacing the current history entry
+so the back button never loops back to the redirect page. The `"*"` key serves as a
+catch-all fallback.
+
+A `<noscript>` `<meta http-equiv="refresh">` element is injected for the `"*"`
+target, covering browsers with JavaScript disabled.
+
+Themes using `<ScavoldLayout>` as their root wrapper get locale redirect handling
+automatically. Themes that manage their own layout root can use the `useRedirect()`
+composable and `<ScavoldLocaleRedirect>` component directly — see `COMPONENTS.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cepharum GmbH, Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# Scavold
+
+Scavold is a VitePress theme framework — a scaffold for building custom VitePress
+themes with Vue at the core. It handles the structural concerns common to every
+content-driven website: page hierarchy, locale management, responsive images, and
+custom containers for Markdown-driven structures on your pages such as galleries, grids etc.
+
+```sh
+bun add vitepress vue scavold
+```
+
+Scavold is currently published as a pre-release, so install it explicitly while
+`latest` does not exist yet:
+
+```sh
+bun add vitepress vue scavold@next
+```
+
+Responsive image generation uses [sharp](https://sharp.pixelplumbing.com/), which
+installs a platform-specific native binary — build environments therefore need to
+be able to fetch it (Node 20 or newer).
+
+Full documentation, including a quick-start guide, component and front matter
+references, and deployment instructions, is available at
+
+**[https://scavold.io](https://scavold.io)**.

package/components/ScavoldArticle.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <article :class="classes" v-bind="dataAttrs">
+    <slot />
+  </article>
+</template>

package/components/ScavoldAside.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <aside :class="classes" v-bind="dataAttrs">
+    <slot />
+  </aside>
+</template>

package/components/ScavoldBreadcrumb.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { useHierarchy } from "../composables/hierarchy";
+import { useScavoldI18n } from "../composables/useI18n.js";
+import ScavoldMenuItems from "./ScavoldMenuItems.vue";
+import type { Scavold } from "../index";
+
+interface BreadcrumbProps {
+
+	/** Include the current page as the last crumb. Default: true. */
+	includeCurrent?: boolean;
+
+	/** Include the root node (typically "Home") as the first crumb. Default: false. */
+	includeRoot?: boolean;
+}
+
+const props = withDefaults( defineProps<BreadcrumbProps>(), {
+	includeCurrent: true,
+	includeRoot: false,
+} );
+
+const { collectAncestors } = useHierarchy();
+const { t } = useScavoldI18n();
+
+const items = computed<Scavold.MenuItem[]>( () =>
+	collectAncestors( props.includeCurrent, props.includeRoot )
+);
+
+const ariaLabel = t( "nav.breadcrumb" );
+</script>
+
+<template>
+  <nav v-if="items.length" class="breadcrumb" :aria-label="ariaLabel">
+    <ScavoldMenuItems :items="items" />
+  </nav>
+</template>

package/components/ScavoldContainer.vue

@@ -0,0 +1,16 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { rootTag, containerName, classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <component
+    :is="rootTag"
+    :class="[containerName, classes]"
+    v-bind="dataAttrs"
+  >
+    <slot />
+  </component>
+</template>

package/components/ScavoldFooter.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <footer :class="classes" v-bind="dataAttrs">
+    <slot />
+  </footer>
+</template>

package/components/ScavoldHeader.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <header :class="classes" v-bind="dataAttrs">
+    <slot />
+  </header>
+</template>

package/components/ScavoldImage.vue

@@ -0,0 +1,33 @@
+<script setup>
+defineProps( {
+	src: { type: String, required: true },
+	srcset: { type: String, default: "" },
+	webpSrcset: { type: String, default: "" },
+	sizes: { type: String, default: "100vw" },
+	alt: { type: String, default: "" },
+} );
+</script>
+
+<template>
+  <picture>
+    <source
+      v-if="webpSrcset"
+      type="image/webp"
+      :srcset="webpSrcset"
+      :sizes="sizes"
+    />
+    <source
+      v-if="srcset"
+      :srcset="srcset"
+      :sizes="sizes"
+    />
+    <img
+      :src="src"
+      :alt="alt"
+      :role="alt ? undefined : 'presentation'"
+      :sizes="sizes"
+      loading="lazy"
+      decoding="async"
+    />
+  </picture>
+</template>

package/components/ScavoldLayout.vue

@@ -0,0 +1,21 @@
+<script setup>
+import { watchEffect } from "vue";
+import { useL10n } from "@cepharum/vue3-i18n";
+import { useRedirect } from "../composables/useRedirect.js";
+import { useHierarchy } from "../composables/hierarchy";
+import ScavoldLocaleRedirect from "./ScavoldLocaleRedirect.vue";
+import ScavoldSimpleRedirect from "./ScavoldSimpleRedirect.vue";
+
+const { isLocaleRedirect, isSimpleRedirect } = useRedirect();
+const { currentLocale } = useHierarchy();
+
+watchEffect( () => {
+	useL10n().setLocale( currentLocale.value );
+} );
+</script>
+
+<template>
+  <ScavoldLocaleRedirect v-if="isLocaleRedirect" />
+  <ScavoldSimpleRedirect v-else-if="isSimpleRedirect" />
+  <slot v-else />
+</template>

package/components/ScavoldLocaleMenu.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { useHierarchy } from "../composables/hierarchy";
+import { useScavoldI18n } from "../composables/useI18n.js";
+import type { Scavold } from "../index";
+
+interface LocaleMenuProps {
+
+	/**
+	 * How to discover available locales.
+	 *
+	 * "auto"      — try explicit, then inherited, then global; use first non-empty result (default).
+	 * "explicit"  — only locales listed in the current page's own `translations` frontmatter.
+	 * "inherited" — explicit translations of current page plus any ancestor's `translations`.
+	 * "global"    — every locale present anywhere in the page hierarchy; link leads to the
+	 *               topmost page of that locale.
+	 */
+	detection?: Scavold.LocaleDetection;
+
+	/**
+	 * When true, include the current locale as a non-navigating item in the list.
+	 * Useful when the locale switcher always shows the full set of locales.
+	 * Default: false
+	 */
+	includeCurrent?: boolean;
+
+	/**
+	 * When true, render nothing if only one locale is available (or none after
+	 * filtering). Default: true
+	 */
+	hideIfSingle?: boolean;
+
+	/** Accessible label for the nav landmark. */
+	label?: string;
+}
+
+const props = withDefaults( defineProps<LocaleMenuProps>(), {
+	detection: "auto",
+	includeCurrent: false,
+	hideIfSingle: true,
+	label: undefined,
+} );
+
+const { collectLocaleLinks, currentLocale } = useHierarchy();
+const { t } = useScavoldI18n();
+
+const links = computed<Scavold.LocaleLink[]>( () =>
+	collectLocaleLinks( props.detection, props.includeCurrent )
+);
+
+const visible = computed( () => {
+	if ( props.hideIfSingle && links.value.length <= 1 ) {
+		return false;
+	}
+
+	return links.value.length > 0;
+} );
+
+const navLabel = computed( () => props.label ?? t( "nav.locale" ).value );
+</script>
+
+<template>
+  <nav v-if="visible" class="locale-nav" :aria-label="navLabel">
+    <ul>
+      <li
+        v-for="link of links"
+        :key="link.locale"
+        :class="{
+          current: link.current,
+        }"
+        :lang="link.locale"
+      >
+        <a
+          v-if="!link.current"
+          :href="link.href"
+          :hreflang="link.locale"
+          :aria-label="link.locale"
+        >{{ link.locale }}</a>
+        <span
+          v-else
+          :aria-current="'true'"
+        >{{ link.locale }}</span>
+      </li>
+    </ul>
+  </nav>
+</template>

package/components/ScavoldLocaleRedirect.vue

@@ -0,0 +1,47 @@
+<script setup>
+import { useData } from "vitepress";
+import { onMounted } from "vue";
+import { isExternalUrl, servableRedirectTarget } from "../lib/redirectTarget.js";
+
+const { frontmatter } = useData();
+
+/**
+ * Picks the best redirect target from the locale map in frontmatter.redirect.
+ * Tries each language in navigator.languages in order; falls back to "*".
+ *
+ * @param {Record<string,string>} map
+ * @returns {string|null}
+ */
+function pickTarget( map ) {
+	for ( const lang of ( navigator.languages ?? [] ) ) {
+		// exact match first (e.g. "de-AT" → "de-AT")
+		if ( map[lang] ) return map[lang];
+		// prefix match (e.g. "de-AT" → "de")
+		const prefix = lang.split( "-" )[0];
+		if ( map[prefix] ) return map[prefix];
+	}
+	return map["*"] ?? null;
+}
+
+onMounted( () => {
+	const map = frontmatter.value.redirect;
+	if ( !map || typeof map !== "object" ) return;
+	const target = pickTarget( map );
+	if ( !target ) return;
+	if ( isExternalUrl( target ) ) {
+		// External locale targets: open in a new tab.  The locale is resolved at
+		// runtime so build-time <meta http-equiv="refresh"> is not an option here.
+		// The click interceptor in lib/index.js does not cover locale-redirect
+		// pages either (the map only contains simple-string redirects), so
+		// window.open() is the correct call.  It is invoked from onMounted which
+		// is async relative to the nav click, but modern browsers propagate
+		// user-activation through the Promise chain long enough for this to work
+		// in practice; popup-blocked fallback is acceptable for a locale redirect.
+		window.open( target, "_blank", "noopener,noreferrer" );
+	} else {
+		location.replace( servableRedirectTarget( target ) );
+	}
+} );
+</script>
+
+<template><!-- redirect handled in onMounted --></template>

package/components/ScavoldMain.vue

@@ -0,0 +1,12 @@
+<script setup>
+import { useContainer, containerProps } from "../composables/useContainer.js";
+
+const props = defineProps( containerProps );
+const { classes, dataAttrs } = useContainer( props );
+</script>
+
+<template>
+  <main :class="classes" v-bind="dataAttrs">
+    <slot />
+  </main>
+</template>

package/components/ScavoldMenu.vue

@@ -0,0 +1,82 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { useHierarchy } from "../composables/hierarchy";
+import ScavoldMenuItems from "./ScavoldMenuItems.vue";
+import type { Scavold } from "../index";
+
+interface MenuProps {
+
+	/** Selects the parent node by path, supporting a `{locale}` placeholder that is
+	 * replaced with the current page's locale at runtime. Takes priority over
+	 * `fromRoot` and `from` when set. Examples: `"de/footer"`, `"{locale}/footer"`. */
+	fromPath?: string;
+
+	/** Absolute depth from root. 1 = top-level pages, 2 = second level, etc.
+	 * When set, `from` is ignored. Nothing rendered if current page has no ancestor at this depth.
+	 * Ignored when fromPath is set. */
+	fromRoot?: number;
+
+	/** Depth relative to current page. 0 = siblings (default), 1 = children,
+	 * -1 = aunt/uncle level, etc. Ignored when fromRoot or fromPath is set. */
+	from?: number;
+
+	/** Additional levels to descend. 0 = flat list (default), 1 = one level of children, -1 = unlimited. */
+	depth?: number;
+
+	/** Expand only the branch leading to the current page. Useful with depth > 0. */
+	activeOnly?: boolean;
+
+	/** Expand all nodes regardless of active branch. Enables sitemap-style rendering.
+	 * activeOnly takes precedence when both are set. */
+	expand?: boolean;
+
+	/** Accessible label for the nav landmark. Required when multiple ScavoldMenu
+	 * instances appear on the same page so screen readers can distinguish them. */
+	label?: string;
+}
+
+const props = withDefaults( defineProps<MenuProps>(), {
+	fromPath: undefined,
+	fromRoot: undefined,
+	from: 0,
+	depth: 0,
+	activeOnly: false,
+	expand: false,
+	label: undefined,
+} );
+
+const { current, ancestorAtDepth, collectItems, resolveByPath } = useHierarchy();
+
+const items = computed<Scavold.MenuItem[]>( () => {
+	let parent: Scavold.HierarchyNode | undefined;
+
+	if ( props.fromPath !== undefined ) {
+		parent = resolveByPath( props.fromPath );
+	} else if ( props.fromRoot !== undefined ) {
+		parent = ancestorAtDepth( current.value, props.fromRoot );
+	} else {
+		let iter: Scavold.HierarchyNode | undefined = current.value;
+		const steps = -props.from;
+
+		if ( steps > 0 ) {
+			for ( let i = 0; i < steps && iter?.parent; i++ ) {
+				iter = iter.parent;
+			}
+
+			parent = iter?.parent;
+		} else if ( steps === 0 ) {
+			parent = iter?.parent;
+		} else {
+			parent = iter;
+		}
+	}
+
+	return collectItems( parent, props.depth, props.activeOnly, props.expand );
+} );
+</script>
+
+<template>
+  <nav v-if="items.length" :aria-label="label || undefined">
+    <ScavoldMenuItems :items="items" />
+  </nav>
+</template>