Frontmatter | NookDocs

Every MDX page carries a YAML frontmatter block between two --- markers at the top. The platform reads these fields for the page title, navigation, SEO, and a handful of per-page overrides.

---
title: Authentication
description: How to authenticate API requests.
icon: lock
tag: NEW
---

Page body starts here.

Core fields

titlestring

Page title. Used as the <h1> (unless the MDX body starts with its own # heading), the <title> meta tag, and the sidebar label when the page appears in navigation. Required in practice — pages without a title fall back to the filename.

Above the title the page shows the section it belongs to — Getting Started over Introduction, say. It comes from the group the page sits in under navigation, not from frontmatter, so there is nothing to set: move a page to another group and the label follows. Pages that aren't listed in navigation show no section label rather than a guess.

sidebarTitlestring

Short label for the sidebar, used instead of title there. The page keeps its full heading; only the navigation gets the shorter form.

Worth setting when a title runs past the rail's width — roughly 23 characters at the default 288px, and fewer on a monospace theme like Terminal. A label that doesn't fit is truncated with an ellipsis and its full text stays available on hover, but a short label reads better than either.

title: Data Processing Agreement (DPA)
sidebarTitle: DPA

descriptionstring

One-line description. Rendered under the title in the rendered page, used as the meta description, shown in search results, and passed to AI retrieval as part of the snippet context.

iconstring

Icon name (Lucide default, or Tabler/FontAwesome depending on config.icons.library). Shown in the sidebar next to the page label and — when the page is a root of a group with directory — inside the generated directory cards.

tagstring

Badge text shown next to the page label in the sidebar (e.g. NEW, BETA, DEPRECATED). Truncates at 8 characters.

hiddenbooleandefault: false

When true, the page is hidden from the sidebar but still accessible by URL. Handy for drafts you want to share via link without advertising.

SEO overrides

ogImagestring

Open Graph image URL for this page specifically. Overrides config.seo.ogImage. 1200×630 PNG recommended for social preview fidelity.

noindexboolean

When true, emits <meta name="robots" content="noindex, nofollow">. Use for private sections, draft pages, or any URL you want out of search engines without removing the content.

Timestamp override

timestampstring (ISO 8601)

Override the "Last updated" date shown at the bottom of the page.

Precedence (highest first):

config.advanced.showTimestamp: false → renders nothing, regardless of frontmatter.
Frontmatter timestamp (this field).
DB updated_at — the git commit mtime from the sync pipeline.

Useful when the git mtime is noisy (bot commits, bulk renames, formatter churn) and you want to pin a meaningful date. Accepts any ISO 8601 form:

---
title: Authentication
timestamp: "2026-04-18"
---

Or with time:

---
timestamp: "2026-04-18T12:00:00Z"
---

API reference pages

Used by pages that auto-generate from an OpenAPI spec:

openapistring

Points at a specific operation in the spec. Format: "<METHOD> <path>" — e.g. "GET /users/{id}". The platform generates the ParamField + ResponseField tables, RequestExample + ResponseExample code samples, and endpoint metadata automatically.

mode'default' | 'wide' | 'custom'

Layout mode. default renders the standard 3-column docs layout. wide removes the right-side TOC column (useful for landing pages). custom strips both columns and the prose style, giving you a blank canvas — for hero / changelog / custom layouts.

Authoring tips

Put the most-visited fields at the top. title then description then icon — makes diffs readable when you bulk-edit pages.
Quote strings with colons or special chars. YAML parses title: GET /users as an object; wrap in quotes: title: "GET /users".
Prefer icon over inline <Icon> components in h1. Frontmatter icon renders consistently in every surface (sidebar, directory cards, AI context); an inline <Icon> only renders in the page body.

Things the platform ignores

Frontmatter is a free-form YAML dict — put whatever you want in it. Fields the platform doesn't read are passed through unchanged (the sync pipeline writes them to pages.frontmatter JSONB) and available for future features or custom MDX templates.

Common custom fields teams add:

author: "Jane Doe" — rendered via a custom <Byline> component
reviewedOn: "2026-01-15" — shown alongside the timestamp for policy / compliance pages
estimatedReadingTime: "5 min" — shown in the hero

None of these are required — they're YOUR fields for YOUR templates.