Frontmatter

A page's YAML frontmatter sits between --- fences at the top of the file:

---
title: Surfaces
description: The surface model on one page
tags: [runes, theme]
---

# Surfaces

Every field below is generated from frontmatter.schema.json — the same schema your editor can validate against — so this lists what refrakt actually reads.

Fields

title

string

Page title. Used for the document title, navigation labels and social cards; falls back to the page's first H1 when omitted.

description

string

Short summary, used for the meta description, social cards and the blurb on link cards.

slug

string

Override the URL segment derived from the filename.

draft

boolean

Exclude the page from the built site and from navigation.

redirect

string

Redirect this URL elsewhere instead of rendering a page.

order

number

Sort position among sibling pages in generated navigation. Lower sorts first.

date

string

Publication date (ISO 8601). Used for ordering and display by blog-style listings.

author

string

Author name, used in article metadata and structured data.

tags

string[]

Free-form labels, filterable with the `field:value` grammar `collection` and `aggregate` share.

image

string

Page image, used for social cards and as the media for link cards.

icon

string

Icon name resolvable by the `icon` rune. `nav layout="cards"` renders it on each child page's card.

tint

string, null

Named tint preset for this page, or for the whole subtree when set in a `_layout.md`. Cascades down the layout chain; an explicit null resets to inherit from the layer above.

tint-mode

"auto" | "light" | "dark"

Initial colour-scheme behaviour. `auto` follows the user's preference; `light` / `dark` lock the server-rendered mode. Cascades down the layout chain.

tint-lock

boolean

Ignore the user's theme preference and hide the theme toggle — for surfaces that should look the same to every visitor. Cascades down the layout chain.

type

string

Register this page as an entity of the named type, so `collection`, `aggregate` and `xref` can find it. This is what drives the entity registry. A `routeRules` entry can set it for a whole subtree instead of per page.

id

string

Explicit entity ID for this page. Defaults to the page's slug.

created

string

Creation date (ISO 8601), overriding what git history or the filesystem reports.

modified

string

Last-modified date (ISO 8601), overriding what git history or the filesystem reports.

Validating frontmatter in your editor

Point your editor's YAML support at the published schema for hover documentation and completion inside --- blocks:

{
  "yaml.schemas": {
    "https://refrakt.md/frontmatter.schema.json": ["**/content/**/*.md"]
  }
}

See Schema for the versioned URLs.

Keeping this page honest

The rows come from site/content/_data/frontmatter-fields.json, generated by scripts/generate-config-reference.mjs. A drift test guards the schema against the Frontmatter interface in both directions, and a freshness test guards the artifact — so a field added to one and not the others fails the build rather than going undocumented.

npm run config:reference

See also

• Tint — how tint, tint-mode and tint-lock cascade
• Entities — what type and id register the page as
• Configuration reference — the same treatment for refrakt.config.json