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 is optional, 10 to 170 characters when given. It is the subtitle
under the title and the meta description. A page without one shows no subtitle,
and every metadata surface (meta tags, search, llms.txt, the agent manifest,
the feed, the share card) uses the first paragraph of the body, cut at 160
characters. That is what you want for imported pages that open with their own
introduction, where a generated subtitle would repeat it. metaDescription
sets a description for those surfaces only, without showing a subtitle, and
metaTitle sets the whole <title> and og:title, with no site suffix.
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 |
hidden | boolean | Page is published and routed, but out of the sidebar, search, the sitemap, the feeds and the previous and next links, and noindexed |
These fields are different. A draft page does not exist on the site. A
noindex page exists and is in the sidebar, but the site never promotes it. A
hidden page exists and is reached by its link only: it is not in the sidebar
even when docs.config.ts lists it, and the build does not insist that it be
listed. Use it for a campaign landing page, or a legacy URL you keep alive.
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.
A change that touches many pages without changing what they say, such as
removing a frontmatter key from every file, should not re-date them all. Put
the line Page-dates: keep in its commit message, and the build dates each
page from the commit before it. With squash merges, the line has to reach the
merged commit. If the repository’s squash message uses the commit details,
write it in the commit. If it uses the pull request description, write it
there.
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
---