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.

---

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

---

hide

Type: boolean | "menu" | "breadcrumb"

Controls whether this page appears in navigation.

Value	Effect
absent / false	Visible everywhere (default)
true	Hidden in menus and breadcrumbs
"menu"	Hidden in menus only
"breadcrumb"	Hidden in breadcrumbs only

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

---
hide: menu
---

---

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>.