Configuration reference: Front matter

Embed

<a href="https://forumulate.com/reference/config-front-matter"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/fbed4fd6-4fd9-4d0a-986b-4bc7e4adc6a2/social-card.svg?v=3e7ae33eec8b" alt="Configuration reference: Front matter" width="600" height="315"></a>

The YAML block at the top of a Markdown page: title, slug, order, the kind and parameters of the piece, and every page setting PATCH …/pages/{id}/metadata takes (SEO, schemaType, layout, audience, …).

Where it is used: Every .md/.mdx file forumulate publish, sync, plan and apply, or the docs importer, reads.

JSON Schema: https://forumulate.com/schemas/2026-12-01/front-matter.json — point your editor at it with "$schema": "https://forumulate.com/schemas/2026-12-01/front-matter.json" (JSON) or # yaml-language-server: $schema=https://forumulate.com/schemas/2026-12-01/front-matter.json (YAML), and check a whole folder with forumulate validate <dir>.

This page is generated from the schema the API validates with; it cannot describe a key the API does not take.

Casing

Every key in a JSON or YAML configuration document (site config, theme, forumulate.yaml, a category) is camelCase, exactly: primaryColor, footerColumns, headerLinks. primary_color and PrimaryColor are unknown keys, refused with the camelCase name in the hint. The one exception is two top-level blocks of a version-2 site manifest, which are snake_case: reader_auth (a list of sign-in configurations) and status_monitors; readerAuth is a different key there, the one-word shorthand readerAuth: atlas.
Front matter is the exception: a key is read in any casing (seo_title, seo-title, SeoTitle all mean seoTitle), and the names other tools use (description, sidebar_label, sidebar_position, image) are read as ours.
Enum values are lower-case ("wide", "system"), except space types and visibilities, which are upper-case ("DOCS", "PUBLIC").
Colours are #rrggbb (or #rgb); lengths that are numbers are CSS pixels.

Keys

Top-level keys and the keys one level inside them. [] marks “each item of a list”.

Key	Type	Required	What it is
`api`	string \| null
`apiLocale`	string \| null		On a language twin of a generated API reference page: the language its words are in. Only a twin carrying its own language here is published as a translation (hreflang, sitemap, language switcher); the import sets it on the twins it writes from `x-translations`. `null` clears.
`apiMethod`	`"GET"` \| `"POST"` \| `"PUT"` \| `"PATCH"` \| `"DELETE"` \| `"HEAD"` \| `"OPTIONS"` \| `"TRACE"` \| `"WEBHOOK"` \| `"SEND"` \| `"RECEIVE"` \| null
`apiPage`	`"landing"` \| `"tag"` \| `"operation"` \| null
`audience`	object \| null
`author`	string
`availability`	`"alpha"` \| `"beta"` \| `"preview"` \| `"ga"` \| `"deprecated"` \| `"experimental"` \| `"new"` \| null
`badge`	object \| null
`canonicalUrl`	any \| string \| `""`
`cmsBinding`	object \| null
`collection`	string		The collection the page belongs to (a folder does the same).
`commentsEnabled`	boolean \| null		false turns comments off on THIS page when the space takes comments; null/absent follows the space.
`comparison`	object \| null
`contentLanguage`	string \| `""` \| null
`coverUrl`	any \| string \| `""`
`customCss`	string \| null		CSS for THIS piece only, after the space theme so it wins. Sanitised and scoped to the reader exactly like the space `customCss` (`@import` dropped, no way out of the <style>).
`customHead`	any \| string \| `""`
`draft`	boolean		Skip this file.
`editUrl`	string \| `false` \| null
`externalUrl`	any \| string \| `""`
`fields`	map		The parameters this page’s space type declares. PATCH semantics: the keys you send are merged into the fields already stored, so sending one field leaves the rest alone, and `null` clears a field. The declared keys, their labels, kinds and options are at `GET /space-types/{TYPE}` under `fields` — for a DOCS page they are `audience` (labelled "Written for"), `appliesTo` and `deprecated`. An undeclared key is refused with a 422 naming the keys that do exist.
`frontMatter`	map
`hero`	object \| null
`hideCover`	boolean
`hideFeedback`	boolean
`hideFromNav`	boolean
`hidePager`	boolean
`hideTitle`	boolean
`hideUpdated`	boolean
`icon`	string		An icon name from `GET /icons?for=page` (see the `PageIconName` enum), an emoji or short symbol (≤ 8 characters, no "/" or ":"), or an image URL. Any other bare word is refused: the reader would print it as text.
`jsonLd`	string \| null		Structured data for this piece, as JSON (object or array of objects). Replaces the automatic markup on this piece (Article/BlogPosting, Event, DiscussionForumPosting/QAPage, the roadmap item’s Article). `null` restores the automatic one.
`keywords`	string[]
`kind`	string		Which kind of page this is, where the space type declares more than one (`pageKinds` at `GET /space-types/{TYPE}`). A CAREERS page is a `role` (listed on the board, apply form, JobPosting markup) or a `page` (how you hire, culture: none of those). Absent means the type’s first kind; `null` clears it. A kind the type does not declare is a 422.
`layout`	`"narrow"` \| `"default"` \| `"wide"` \| `"full"` \| `"center"` \| `"custom"`
`lesson`	object
`lesson.assignment`	object
`lesson.audio`	object
`lesson.discussion`	object
`lesson.exam`	object
`lesson.flipbook`	object
`lesson.generatedCaptions`	map
`lesson.kind`	`"standard"` \| `"video"` \| `"audio"` \| `"pdf"` \| `"slides"` \| `"flipbook"` \| `"assignment"` \| `"discussion"` \| `"survey"` \| `"live"` \| `"exam"` \| `"package"`	yes
`lesson.live`	object
`lesson.minLevel`	integer \| null
`lesson.pdf`	object
`lesson.slides`	object
`lesson.survey`	object
`lesson.video`	object
`llms`	boolean		`false` keeps this page out of the llms.txt, llms-full.txt and llms-guides files (of its space and of its site). It stays published and linked; `searchExclude` is the reader search, `noindex` the search engines.
`locale`	string		The page’s language, when the file name does not say.
`metadata`	map		Any other key `PATCH …/pages/{id}/metadata` takes, merged as written.
`navClass`	string \| null
`navData`	map \| null
`navFont`	`"mono"` \| null
`navKind`	`"separator"` \| `"heading"` \| null
`navTitle`	any \| string \| `""`
`nofollow`	boolean
`noindex`	boolean
`ogDescription`	string \| null		og:description / twitter:description.
`ogTitle`	string \| null		og:title / twitter:title.
`onThisPage`	`"auto"` \| `"always"` \| `"never"` \| null		Whether THIS page carries the "on this page" rail: `auto` (the surface default), `always` or `never`. Beats the space theme’s `onThisPage`; `null` or absent means the space decides.
`order`	number		Position among siblings (lower first).
`owner`	string \| null
`pageChrome`	boolean
`pager`	object \| null
`params`	map		The piece’s declared parameters (a role’s location, a document’s version).
`parentSlug`	string \| null		The slug of the page this one nests under.
`preset`	string \| null		Which kind of piece this is, where the space holds more than one.
`redirect_from`	string \| string[]		Old addresses that redirect here.
`related`	string[] \| null
`schemaType`	any \| `"WebPage"` \| `"AboutPage"` \| `"ContactPage"` \| `"ProfilePage"` \| `"SoftwareApplication"` \| `"Product"` \| `""`
`searchExclude`	boolean		Leave this page out of the reader search and the site search. It is still published, linked and in the sitemap; use `noindex` for search engines.
`sections`	map		Markdown per named slot, for a multi-slot page type.
`seoDescription`	string
`seoTitle`	string
`shareImageUrl`	string \| `""` \| null		The og:image / twitter:image for this piece, separate from its cover. Wins over the cover and over the generated social card.
`slug`	string		The address segment. Defaults to the file name.
`socialBadge`	object \| null		This piece’s badge on its generated social card, over the space’s `seo.socialCard.badge`: another `field`, literal `text` ("Sold out"), a `label`, or `hide: true` for no badge. `null` goes back to the space’s badge.
`sourcePath`	string \| null
`subtitle`	any \| string \| `""`
`tags`	string[]
`template`	`"doc"` \| `"splash"`
`theme`	object \| null		A partial theme for this piece — colours, palettes, fonts, typography, colorScheme, components, contentWidth, layout, motion, and its OWN type’s namespace (`post` on a blog post, `changelog` on a release, `events` on an event, `roadmap`, `status` on an incident, `faq`/`careers` (+`docs`) on a question/role, `legal`, `contact`, `courses`, `forum`, `docs`; another type’s namespace is refused) — layered over the space’s (which is over the site’s). On a post, release, event or legal document `PATCH` it MERGES key by key like the space theme’s PATCH, and `null` clears at any depth (`{"paletteDark": null}`); a page’s metadata replaces it whole. Unknown keys are refused by name. `null` clears all of it.
`themePatch`	object		A slice of the theme for THIS page only: `components` (any block look) and `docs.pageHead`, `docs.toc`, `docs.articleWidth`, `docs.pageActions`, `docs.frame`, `docs.panel`, `docs.feedback`, `docs.pager`, `docs.api.titleSize`, `docs.blocks.prompt.icon`. Merged over the space theme for this page; unknown keys are refused (422). Sent whole; `null` clears it.
`themePatch.components`	object
`themePatch.docs`	object
`title`	string		The page title. Defaults to the first `# heading`.
`titleAlign`	`"start"` \| `"center"`
`tocLevels`	object \| null
`twitterCard`	`"summary"` \| `"summary_large_image"` \| null		`summary` (thumbnail) or `summary_large_image` (the default).

Common mistakes

Each of these is answered with a did-you-mean by the API’s 422 and by forumulate validate.

Where	You wrote	We read	Why
top level	`description`	`seoDescription`	Read as ours: another tool’s name for the same field.
top level	`summary`	`seoDescription`	Read as ours: another tool’s name for the same field.
top level	`sidebar_label`	`navTitle`	Read as ours: another tool’s name for the same field.
top level	`nav_label`	`navTitle`	Read as ours: another tool’s name for the same field.
top level	`short_title`	`navTitle`	Read as ours: another tool’s name for the same field.
top level	`linkTitle`	`navTitle`	Read as ours: another tool’s name for the same field.
top level	`hidden`	`hideFromNav`	Read as ours: another tool’s name for the same field.
top level	`nav_exclude`	`hideFromNav`	Read as ours: another tool’s name for the same field.
top level	`sidebar_hidden`	`hideFromNav`	Read as ours: another tool’s name for the same field.
top level	`image`	`coverUrl`	Read as ours: another tool’s name for the same field.
top level	`cover`	`coverUrl`	Read as ours: another tool’s name for the same field.
top level	`cover_image`	`coverUrl`	Read as ours: another tool’s name for the same field.
top level	`og_image`	`shareImageUrl`	Read as ours: another tool’s name for the same field.
top level	`social_image`	`shareImageUrl`	Read as ours: another tool’s name for the same field.
top level	`canonical`	`canonicalUrl`	Read as ours: another tool’s name for the same field.
top level	`lang`	`contentLanguage`	Read as ours: another tool’s name for the same field.
top level	`language`	`contentLanguage`	Read as ours: another tool’s name for the same field.
top level	`toc`	`onThisPage`	Read as ours: another tool’s name for the same field.
top level	`sidebar_position`	`order`	Read as ours: another tool’s name for the same field.
top level	`nav_order`	`order`	Read as ours: another tool’s name for the same field.
top level	`weight`	`order`	Read as ours: another tool’s name for the same field.
top level	`position`	`order`	Read as ours: another tool’s name for the same field.
top level	`openapi`	`api`	Read as ours: another tool’s name for the same field.

The Forumulate teamUpdated Nov 4, 2026

Was this page helpful?