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 at build time to drive navigation, localisation, redirects, and URL aliasing. All keys are optional unless noted otherwise.

---
title: My page title
label: Short label
order: 10
locale: de
---

---

title

Type: string

Display title for the page. Used in menus, breadcrumbs, and the browser <title> element.

When absent Scavold falls back to the first # heading in the page body, then to the path segment.

---
title: Datenschutzerklärung
---

---

label

Type: string

Short navigation label used in menus and breadcrumbs instead of title. Useful when the full page title is too long for compact navigation.

---
title: Allgemeine Geschäftsbedingungen
label: AGB
---

---

order

Type: number

Controls the sort position of this page among its siblings. Pages are sorted by order ascending; pages without order follow at the end in filename order. Negative values are permitted.

Using multiples of 10 leaves room to insert pages later without renumbering existing ones.

---
order: 20
---

A section with mixed ordered and unordered pages:

10  → kontakt.md
20  → leistungen/
    (no order) → agb.md        # follows in filename order after ordered pages
    (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 root-relative without a leading slash. The .md extension is optional.

---
url: de/impressum
---

Menu links and breadcrumbs produced by Scavold automatically use the alias URL.

If two pages declare the same url value, the build aborts with an error naming both conflicting files. So does an alias that lands on a path another page already owns as its own file — url: de/kontakt next to a pages/de/kontakt.md. VitePress identifies a page by its path flattened into one name, slash becoming underscore, and uses that name for the page's bundle entry, its server module and its client chunk; two pages meeting there overwrite each other's output instead of one winning. A file name that spells out a path (de_kontakt.md beside de/kontakt.md) and a pair differing only in letter case collide the same way. Prefer - over _ as the word separator in page names and none of it can arise.

To move a page and keep its URL, rename the file and give the moved page the old URL as its alias — not a second file left behind at the old path.

---

locale / lang

Type: string (BCP 47 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; when both are present, locale takes precedence.

---
locale: de
---

Scavold uses the resolved locale to:

• drive the locale switcher (<ScavoldLocaleMenu>)
• select the correct branch in locale-conditional redirects
• resolve {locale} and {lang} placeholders in <ScavoldMenu from-path="…">

---

translations

Type: object — map of BCP 47 locale code → relative page path

Declares the counterpart pages in other locales. Used by <ScavoldLocaleMenu> to offer direct links to the same content in a different language.

---
translations:
  en: en/about.md
  fr: fr/a-propos.md
---

Paths are relative to 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 to en/about.md at build time — provided that page has no explicit translations entry for that locale already. You only need to declare the link on one side.

The common pattern with detection="inherited" in <ScavoldLocaleMenu> is to declare translations on a section's index.md — all child pages that have no own translations entry then link to the section instead of showing nothing:

pages/
  de/
    products/
      index.md        ← declares translations: { en: en/products/index.md }
      widget-a.md     ← no translations — inherited mode links to en/products/
      widget-b.md     ← no translations — inherited mode links to en/products/
  en/
    products/
      index.md

---

date

Type: string (ISO 8601) — e.g. 2026-06-21 or 2026-06-21T14:30:00Z

Publication date of the page. Read by <ScavoldPageList> to order entries chronologically and to show a date per entry, and by the RSS feed, which announces only pages that carry one.

---
date: 2026-06-21
---

A date-only value is normalised to midnight UTC and rendered in UTC as well, so it never shows up as the neighbouring day in another time zone. Pages without a date sort last in both date orders.

---

excerpt / description

Type: string

Introductory text shown for this page wherever it is teased — in a <ScavoldPageList> with the teaser flag, for example.

---
excerpt: Wie wir den Schulhof an einem Nachmittag umgestaltet haben.
---

When neither key is declared, Scavold derives the text from the page's opening prose at build time: headings, images, code and container fences are dropped, the remaining text is trimmed to excerpt_length characters at a word boundary and marked with an ellipsis. Declaring excerpt is therefore an override, not a prerequisite.

description is accepted as an alias, since sites often already maintain it for search engines. excerpt wins when both are present.

---

image

Type: string — path relative to the media folder

Lead image of the page, used as its teaser image in a <ScavoldPageList> with the images flag.

---
image: /schulhof.jpg
---

The file goes through the responsive image pipeline like any image in a page body, so a teaser gets the same srcset and WebP variants. When the key is absent, the first image in the page body is used instead.

---

hide

Type: boolean | "menu" | "breadcrumb" | "list" | "feed" | string[]

Controls the surfaces this page appears on. Each value names one of them; true covers all — which is what an unfinished post wants, reachable by URL and announced nowhere.

Value	Effect
absent / false	Visible everywhere (default)
true	Hidden everywhere: menus, breadcrumbs, page lists and the feed
"menu"	Hidden in menus only
"breadcrumb"	Hidden in breadcrumbs only
"list"	Hidden in page lists only
"feed"	Left out of the RSS feed only
[ "menu", "feed" ]	Kept off exactly the surfaces named

Hidden pages are still served at their URL and still exist in the hierarchy tree. Affects rendering in <ScavoldMenu>, <ScavoldBreadcrumb> and <ScavoldPageList>.

---
hide: menu
---

---

aliases

Type: string | string[]

Former addresses this page replaces — what a site declares when it takes over from an existing website.

---
aliases:
  - /kontakt.html
  - kontakt.php
---

Written as they stood in the browser, with or without a leading slash; a fragment is dropped, a query string kept. Scavold compiles them into cratly-redirects.json in the build output — 301 per inherited address — which the deploy step translates for whatever serves the site.

Keeping an address is better than redirecting to it: a redirect passes a ranking on, a page answering at the old address never spends it. Where the legacy path can be a file, url does that and needs no server support at all.

The build stops when two pages claim the same address, and when an address is one the site serves itself — the redirect would hide that page.

---

redirect

Type: string | object

Declares a redirect from this page to another URL. Two forms are supported.

Unconditional redirect

A plain string, or an object with only a "*" key, redirects all visitors regardless of locale. Compiled into VitePress rewrites at build time — the original URL is never served.

---
redirect: other-page.md
---

Locale-conditional redirect

An object with locale keys routes visitors based on their browser language preferences (navigator.languages). Handled client-side on first render.

---
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. The "*" key is a catch-all fallback.

A <noscript> <meta http-equiv="refresh"> element is injected for the "*" target to cover 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 useRedirect() and <ScavoldLocaleRedirect> directly — see <ScavoldLayout>.