Frontmatter
Every field a page can declare, what it controls, and which fields the build requires, as defined and enforced in src/content.config.ts.
A page declares only what it is. src/docs.config.ts controls where the page
sits in the sidebar. That includes its category, its section label, and its
neighbours. The page URL is its path under content/.
The schema is src/content.config.ts.
The build enforces this schema. If frontmatter is invalid or incomplete, the
build stops and reports the file at fault.
Required
| Field | Type | Purpose |
|---|---|---|
title | string, min 2 | Page title, browser title, and the # heading of the Markdown twin |
description | string, 10–170 | Introductory summary and meta description |
Presentation
| Field | Type | Purpose |
|---|---|---|
sidebarTitle | string | Shorter label for the sidebar when the title is long |
icon | string | Icon name, shown beside the sidebar label. See icons |
badge | string | Small pill beside the sidebar label, e.g. New |
rightRail | toc | custom | Defaults to toc. Set custom only when the page replaces the table of contents with rail-capable components |
Publication
| Field | Type | Purpose |
|---|---|---|
draft | boolean | Keeps the page in the repository and out of every output. See Drafts |
noindex | boolean | Page stays reachable and in the sidebar, but out of search, the sitemap, the updates feed and the LLM corpus |
These two fields are different. A draft page does not exist on the site. A
noindex page exists, but the site never promotes it.
One file decides publication:
src/lib/published.ts.
Every part of the code that lists pages reads the collection through this
file, instead of writing its own filter. This keeps the meaning of
“published” consistent across all eleven places that check it.
Dates
| Field | Type | Purpose |
|---|---|---|
updated | date | Overrides the last-modified date, which otherwise comes from the file’s last commit |
published | date | First publication date, when it differs meaningfully from the last edit |
Set updated when a change is substantial and the commit history does not
show that. A typo fix should not reset a page’s freshness.
Social
| Field | Type | Purpose |
|---|---|---|
image | string | Replaces the generated share card |
imageAlt | string | Alt text, when a custom image is supplied |
A page that sets neither still gets a full metadata set: a share card generated from its title, a canonical URL, and structured data.
API endpoint pages
Set these to render the three-column API reference layout for one operation in your OpenAPI document. Normal prose pages are unaffected.
| Field | Type | Purpose |
|---|---|---|
pageType | api-endpoint | Selects the endpoint layout |
apiMethod | GET | POST | PUT | PATCH | DELETE | Must match an operation in the spec |
apiPath | string | Must match that operation’s path |
apiOperationId | string | Optional override |
apiTag | string | Optional override |
Full walkthrough in API reference pages.
A complete example
---
title: Progressive rollout
sidebarTitle: Rollouts
description: Increase a flag's exposure in stages that halt themselves when a guard metric moves.
icon: activity
badge: New
updated: 2026-08-01
---