/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Configuration Frontmatter

Frontmatter

Page-level configuration with YAML frontmatter.

23 min read

Frontmatter is YAML metadata at the top of each MDX file. It controls page settings, SEO, layout, and protocol-specific rendering.

Basic Frontmatter

Every page should have at minimum a title:

yaml
---
title: Getting Started
---

Common Fields

FieldTypeDescription
titlestringPage title (required)
descriptionstringMeta description for SEO
sidebarTitlestringShorter label for the sidebar. See Navigation Fields
tagstringA short badge beside the page in the sidebar, such as New or Beta. See Sidebar badge
hiddenbooleanDrop from the sidebar; still built and served. See Navigation Fields
noindexbooleanKeep the page out of search engines. See SEO Fields
sectionstringWhich section — and so which header tab — the page belongs to. See Section and tab placement
iconstringIcon beside the page's sidebar entry. See Sidebar icons
draftbooleanDrop from the sidebar and mark noindex. See Navigation Fields
sidebarbooleanShow/hide the navigation sidebar. See Feature toggles
tocbooleanShow/hide the table of contents. See Feature toggles
audiencestring or listAudience tags allowed to see the page. Gated pages leave navigation, search and the AI assistant for other visitors. See Audience gating
cssstringA stylesheet for this page only, such as ./pricing.css. See Page stylesheet
Note
Every field on this page is read

Every key documented here has an effect on your site. A few apply only on doc engine v1 and are marked.

The settled core set

title, description, sidebarTitle, icon, hidden, noindex and tag are the page keys every page type reads, with one name each. Two older spellings are deprecated in their favour.

Unknown keys

A key Syntext doesn't read is ignored, and the build log, stx check and the web editor warn with the closest valid key:

text
docs/guide.mdx:3: Unknown key "descripton" is ignored. Did you mean "description"?

Values of enum keys such as layout, dir or protocol are checked the same way. Unknown keys follow the deprecation policy (code frontmatter.unknown-key): today they're warnings.

icon puts a small glyph beside the page's entry in the navigation sidebar. It takes an icon name such as key, rocket or settings — the same names <Card>, <Accordion>, <Step> and <Tab> accept, so a name that works on one works on all of them. Doc sites draw them from Untitled UI, the icon set the dashboard uses.

yaml
---
title: Authentication
icon: key
---

On doc engine v2 sites using the sections navigation (Orbit's default), every page shows an icon: a page without icon, or with a name Syntext doesn't know, shows a plain page icon. The same short names tab icons accept (guides, cli, api, …) work here too.

Three things worth knowing:

•
An unknown name costs you the glyph, not the entry. A typo renders the page in the sidebar with no icon. It never prints the name as text, and the build does not fail.
•
A method chip wins. An API page whose title starts with GET, POST and so on already shows a method chip in that slot, and keeps it.
•
It is decorative. The glyph is aria-hidden, because the link text beside it already names the page. A screen reader reads "Authentication", not "key, Authentication".

In the other navigation styles, a sidebar where no page sets icon renders exactly as it did before — the rule that turns the row into a flex row only matches a row that has a glyph.

Example

yaml
---
title: Authentication Guide
description: Learn how to authenticate with the API using API keys or OAuth.
icon: key
---

How title and description Render

Beyond metadata, title and description can render as visible page content:

•
If the page body contains no <h1> (no # Heading), the build synthesizes one from the frontmatter title, and renders description as a lead paragraph directly below it.
•
If the body already has an <h1>, nothing is synthesized — the frontmatter values are used only for metadata (browser tab, sidebar, SEO).
•
The lead paragraph is skipped when the body's first paragraph already starts with the same text as description, so you won't see it twice.

This means both authoring styles work:

Frontmatter-only (Mintlify style)Explicit heading
---
title: Authentication Guide
description: Learn how to authenticate with the API.
---
Syntext supports two authentication methods...
Note

Pick one style per page: either rely on the frontmatter title or write an explicit # Heading — not both. If your body starts with # Authentication Guide, no heading is synthesized, so there's no double render; but mixing styles across pages makes headings inconsistent.

Layout Options

Control page structure with the layout field:

yaml
---
title: Welcome
layout: centered
---
LayoutDescription
defaultThree-column: sidebar + content + TOC
centeredSingle column, centered content — no sidebars; ideal for landing pages. Doc engine v1 only; v2 treats it as default
full-widthSingle column, full width — the sidebar and the on-this-page column both go
landingKeeps the left sidebar, drops the on-this-page column, and centres a wider content column — for a homepage that stays inside the docs navigation. Doc engine v1 only; v2 treats it as default
wideDoc engine v2 only: the header, then your body across the page, then the site footer — no sidebar, on-this-page column or previous/next links. Home components run full width; other content sits in a 1136px column. For a home built from home components. v1 treats it as default

Hiding the right column

Set hideRightSidebar: true to drop the right-hand column and let the content span to the right edge while keeping the left navigation sidebar:

yaml
---
title: API Reference
hideRightSidebar: true
---

This works on guide pages (hides the "On this page" TOC) and on prose pages inside the API Reference section (overview and hand-written pages), where it removes the reserved code-example column. Endpoint pages ignore it — the request/response column always stays.

Background Customization

For landing pages or special sections:

yaml
---
title: Welcome
layout: centered
background: "#0a0a1a"
---

Solid Color

yaml
---
background: "#050510"
---

Gradient

yaml
---
background: "linear-gradient(135deg, #0a0a1a 0%, #1a0a2e 100%)"
---

Light and dark backgrounds

Give background an object to set a different value for each colour mode:

yaml
---
background:
light: "#f6f7fb"
dark: "linear-gradient(135deg, #0a0a1a 0%, #1a0a2e 100%)"
---

Background Image

yaml
---
backgroundImage: "/assets/hero-bg.png"
---

The image is always drawn with background-size: cover and background-position: center. There are no keys to change either. When background is also set, background wins and the image is not used.

background and backgroundImage apply to guide pages on doc engine v1 sites only. API pages and doc engine v2 sites ignore them.

Full width

yaml
---
layout: full-width
---

To let the content span the full width, use layout: full-width. layout: centered also implies it. Guide pages only.

fullWidth: true is the deprecated spelling of the same thing — see Deprecated keys.

Page stylesheet

Add CSS to one page with css — a path to a .css file in your docs folder:

yaml
---
title: Pricing
css: ./pricing.css
---
•
./pricing.css is relative to the page; /styles/pricing.css starts from the docs folder.
•
The file must be a .css file inside your docs folder, at most 50KB. URLs aren't accepted.
•
It applies only to this page, after the site-wide CSS from _syntext/*.css and before pasted Custom CSS.
•
It's CSS only, follows the same rules as _syntext/*.css, and applies while CSS from your docs is on (the default).
•
Works on doc engine v1 and v2.

A path that's wrong fails the publish with a message naming the page, such as css "./x.css": file not found (x.css in the docs folder); stx check and the web editor show the same. See Custom code from your docs for every message and its fix.

SEO Fields

Optimize for search engines and social sharing:

yaml
---
title: API Reference
description: Complete API reference for all endpoints.
ogImage: /images/api-og.png
noindex: false
canonical: https://docs.example.com/api
---
FieldDescription
descriptionMeta description (150-160 chars ideal)
ogImageOpen Graph image for social sharing. Absolute, or site-relative (/images/og.png). Overrides the site-wide card from syntext.json
noindextrue excludes the page from search engines (noindex, nofollow), on doc engine v1 and v2 sites. noIndex is the deprecated spelling
canonicalCanonical URL for duplicate content. Replaces the generated canonical; og:url still names this page

Control how the page appears in navigation:

yaml
---
title: Advanced Configuration
sidebarTitle: Advanced
sidebarPosition: 5
tag: Beta
hidden: false
---
FieldDescription
sidebarTitleLabel to use in the sidebar instead of title
tagA short badge beside the page in the sidebar (New, Beta). At most 20 characters
sidebarPositionSort order within the section — lower sorts higher
hiddenDrop the page from the sidebar; it is still built and still served
draftDrop the page from the sidebar and mark it noindex; it is still served

tag draws a small badge in your accent colour beside the page's sidebar entry:

yaml
---
title: Webhooks v2
tag: New
---

Keep it to a word or two — text longer than 20 characters is cut at 20. It renders on doc engine v1 and v2 sites. A site where no page sets tag renders exactly as before.

Note
hidden and draft never unpublish a page

Both keys change navigation only. A page marked hidden or draft is still compiled, still written and still reachable at its URL — every existing link and bookmark keeps working. draft additionally sets noindex, so the page leaves search engines while keeping its address. Neither key deletes anything.

Note
syntext.json navigation still wins

sidebarPosition reorders pages within their own section, and only pages that navigation in syntext.json did not already place. Where navigation lists a page, config order is authoritative and sidebarPosition is ignored — so adding a position to one page cannot reshuffle a hand-ordered sidebar. Pages without a position keep their existing relative order.

Section and Tab Placement

Every page belongs to exactly one section. The section decides which header tab the page sits under, which sidebar it renders, and where prev/next pagination can go — pagination never crosses a section boundary.

Two frontmatter fields set it:

FieldTypeDescription
sectionstringThe section name, verbatim. Use the exact name of a header tab from tabs when you have one
categorystringA coarser alias, mapped to a built-in section
yaml
---
title: Rate Limits
section: API Reference
---

category maps a handful of well-known words onto the built-in sections, which is convenient when migrating from a platform that used them:

category valueSection
api, referenceAPI Reference
sdk, client, librarySDKs
changelog, releasesChangelog
guide, tutorialGuides

Any other value is ignored. section wins over category when both are set.

Precedence

A page's section is resolved in this order, each step overriding the one before:

1.
Path — a slug starting api/ or reference/ gives API Reference, sdk/ / client/ / library/ gives SDKs, changelog/ / releases/ gives Changelog. Everything else falls back to Guides.
2.
Frontmatter — section, else category.
3.
Tab URL match — when tabs is configured, the tab whose URL's first path segment matches the page's first slug segment claims the page. Longer tab URLs are tried first, and a tab with url: "/" claims index plus any page whose slug has no / in it. A page matching no tab keeps whatever step 2 gave it.
4.
navigation[].tab — a navigation group's tab always wins, provided the name is one of your tabs. See Navigation.
Warning

Step 3 is why section alone can look like it does nothing on a site that has tabs: a page at guides/rate-limits marked section: API Reference is pulled straight back into the Guides tab by the URL match. Either move the page under that tab's URL prefix, or pin its navigation group with tab, which outranks both.

Protocol Frontmatter

For API documentation, specify the protocol to get specialized rendering.

protocol must be one of rest, websocket, graphql, grpc or event. Any other value is ignored and the page renders as an ordinary guide, rather than as a half-built API page.

Only the keys belonging to the page's own protocol are read. A rest page that also carries a broker: key — left over from a copied template, say — ignores it instead of rendering a broker badge.

Note

How values are read. Frontmatter is YAML, and YAML gives types to unquoted values: title: 2026 is a number, method: 200 is a number, title: ~ is empty, and tags: [a, b] is a list.

Where a single piece of text is expected, a number or true/false is used as written — version: 2 means "2". A list, a nested block or an empty value has no sensible text, so the key is treated as absent and the documented default applies. Nothing here fails a build: a page with an odd value renders with that one key ignored, and the rest of the site is unaffected.

Quote any value you want kept exactly as typed:

yaml
---
title: "2026" # text, not the number 2026
method: "GET"
---

REST / HTTP

yaml
---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
description: Create a new user account.
---

Renders a colored method badge (POST = green) and endpoint path.

REST pages also read three keys that configure the "Try it" console:

yaml
---
protocol: rest
method: GET
endpoint: /v1/users
baseUrl: "https://api.example.com"
servers:
- url: "https://api.example.com"
description: Production
- url: "https://sandbox.example.com"
description: Sandbox
auth:
type: bearer
label: API key
description: "From Settings › API keys in your dashboard."
---
FieldDescription
baseUrlBase URL the console sends requests to
serversList of environments, each a URL string or { url, description } — description labels the entry in the selector (name is not read). With one entry, it's the base URL; with more than one, the console shows a base-URL selector. On doc engine v1, a list of more than one must use the { url } object form. Overrides baseUrls in syntext.json
authHow this endpoint authenticates, for the console and the generated request samples. Overrides auth in syntext.json; see Declaring auth below. With nothing declared here or in syntext.json, the page shows no credential at all: no Authorization field in the console and no auth header in the samples

Pages generated from an OpenAPI spec get all three written for them.

Declaring auth

auth takes one scheme, a list of schemes the endpoint accepts as alternatives, or none:

FieldDescription
typebearer (sent as Authorization: Bearer …), basic (the reader types username:password; it's sent base64-encoded), apiKey (needs name), or oauth2 / openIdConnect (a token the reader already has, sent as a Bearer token)
nameThe header, query parameter or cookie that carries the credential. Required for apiKey; bearer defaults to Authorization
inheader (the default), query or cookie. A docs page can't set a cookie on your API, so for a cookie key the console explains that and Copy as code includes it
labelWhat the console asks for, such as Session token or API key. Defaults: Bearer token, Username and password, the key's name
descriptionOne sentence under the field, such as where to get the credential
bearerFormatFor example JWT. The samples then write <jwt> instead of <token>
prefixWritten before the value. Defaults to "Bearer " for bearer, "Basic " for basic, nothing for a key
yaml
# A public endpoint on a site whose syntext.json declares a credential
auth: none
# An endpoint that takes an API key or a session token
auth:
- type: apiKey
name: X-API-Key
label: API key
- type: bearer
label: Session token
bearerFormat: JWT

With a list, the console shows a chooser and the samples use the first scheme. Placeholders are never real keys: <jwt> for bearerFormat: JWT, <token> for other bearer tokens, <api-key> for a key, and YOUR_API_KEY in a query string. Nothing is inferred from the page's text. The v1 form, { name, label, in, prefix }, still works: a "Bearer " prefix reads as bearer, "Basic " as basic, anything else as a key.

On doc engine v2, a REST page's examples sit in the right-hand column:

•
<RequestExample> and <ResponseExample>, and also ordinary sections whose heading is Example, Examples, Request, Request example, Response, Responses or Response — 200 OK (any case): their code blocks and CodeGroups move to the right column, requests first, and a heading left with nothing under it is dropped. A status in the heading (Response — 201 Created, or a nested ### 404) labels the response. Prose, notes and field lists stay where they are.
•
With no examples, the page gets generated ones: a request built from its ParamFields (path, query, header and body fields; a ParamField under a response heading counts as part of the response) and a response per documented status built from its ResponseFields. An authored response always wins over a generated one.
•
With an authored request, its tabs come first, exactly as written, and a generated tab is added for each request language they leave out. A tab's language is read from its title (cURL (raw body), Python (httpx), Node.js, C#), then its fence; a shell tab counts as cURL only if it runs curl. Turn this off with generateAlongsideAuthored: false.
•
The generated tabs send the author's own request, read from the first cURL command that can be parsed: method, URL, headers, body, -F multipart parts with @file uploads, --data-binary and raw text bodies. $NAME and ${NAME} stay environment references, so each language reads them from the environment (process.env, os.environ, os.Getenv, …). With no usable cURL, the request is built from the page's ParamFields, plus the authored JSON body if there is one. When the authored request has several variants (a multipart upload and a raw body, say), every generated language follows the first; the others stay in their own authored tabs. Each <RequestExample> on a page is handled separately.
•
A page with no examples and no fields gets no empty column: the content takes the full width.
FieldDescription
requestLanguagesLanguages of the generated request sample on this page, in tab order: curl, javascript, typescript, node, python, python-httpx, go, ruby, php, java, csharp, rust, swift, kotlin and http. Overrides api.requestLanguages in syntext.json. With an authored request example, only the languages it leaves out are generated. Doc engine v2 only
generateAlongsideAuthoredtrue (the default) adds a generated tab beside an authored request example for each language it leaves out; false shows the authored example alone. A page with no authored request example always gets generated ones. Overrides api.generateAlongsideAuthored in syntext.json. Doc engine v2 only

WebSocket

yaml
---
title: Order Created Event
protocol: websocket
event: order.created
direction: server-to-client
description: Fired when a new order is placed.
---

GraphQL

yaml
---
title: Create Order Mutation
protocol: graphql
operation: mutation
name: createOrder
description: Create a new order.
---

gRPC

yaml
---
title: Create Payment
protocol: grpc
service: PaymentService
rpc: CreatePayment
description: Create a new payment via gRPC.
---

Event-Driven

yaml
---
title: Order Confirmed
protocol: event
channel: orders.confirmed
broker: kafka
description: Published when an order is confirmed.
---

Feature Toggles

Enable or disable page features:

yaml
---
title: Quick Reference
toc: false
sidebar: false
feedback: true
editUrl: https://github.com/org/repo/edit/main/docs/quick-ref.mdx
---
FieldDefaultDescription
toctrueShow the on-this-page table of contents
sidebartrueShow the left navigation sidebar. Doc engine v1 only
feedbacktrueShow the "Was this page helpful?" widget. Doc engine v1 only
editUrl—URL for an "Edit this page" link. No link is rendered unless you set it

Setting any of the first three to false removes that column or widget for this page only, and the remaining columns widen to fill the space. toc: false is the same thing as hideRightSidebar: true; use whichever reads better.

Note
editUrl has no automatic default

Syntext does not know your repository's remote, branch or path prefix, so it cannot derive an edit link for you — and a guessed link that 404s is worse than no link. The "Edit this page" affordance appears only on pages that set editUrl explicitly.

On an endpoint page, toc: false is ignored: the right-hand column there is the request and response rail, not a table of contents, and hiding it would take the code samples with it.

Language and Direction

FieldDefaultDescription
langsite locale, else enBCP-47 tag for this page, e.g. ar-EG
dirderived from langltr or rtl, overriding what the language implies
yaml
---
title: ابدأ من هنا
lang: ar
---

The page's <html> element carries both. Direction is derived from the language subtag — Arabic, Hebrew, Persian, Urdu, Pashto, Kurdish, Divehi, Yiddish and the rest read right to left — and a script subtag such as az-Arab wins over the language. Set dir only when you need to disagree with that.

A right-to-left page mirrors its layout automatically: the navigation sidebar moves to the right, the table of contents to the left, indents and borders swap ends, and the arrows that point — prev/next, breadcrumb separators — flip. Code blocks, URLs and endpoint paths stay left to right inside right-to-left prose.

To set the language for a whole site rather than one page, use locale in syntext.json.

Home page

On a doc engine v2 site, docs/index.mdx is your home page, and it can look however you want. Build it from the home components — each is drawn in your preset's home style, and each one used empty fills itself from your site:

mdx
---
title: Acme Docs
description: Payments, payouts and webhooks in one API.
layout: wide
---
<Hero title="Build with Acme" description="Payments, payouts and webhooks in one API.">
<SearchBar mode="both" suggestions="popular" />
[Quickstart](/quickstart) [API reference](/api-reference)
</Hero>
<QuickStart />
<SectionCards />
<LatestUpdates count={3} />
ComponentWhat it draws
<Hero title>The home hero: headline, lede, buttons, install command and a search box
<SearchBar size="lg">The home search box, with Search / Ask and suggestion chips
<QuickStart>Numbered first steps
<SectionCards>A card per section
<ApiGroups>The API reference's endpoint groups
<SdkList>Your SDKs
<CommandList>CLI commands
<PopularPages>The most read pages
<LatestUpdates>The newest changelog entries
<SupportCard>A contact panel

They work on any page, not only the index. A page whose body opens with <Hero title> uses the hero as its head, so the page title and description aren't shown twice.

Pick the frame with layout: wide for a home with no sidebar, or leave it out to keep the sidebar and table of contents. With the normal frame, the section that holds only the index shows as a header tab like any other; with wide it stays hidden, because the logo already links home.

Which index pages render as a page

On doc engine v2, every index page shows only its own content. The generated home ended on 16 November 2026 — see Since 16 November 2026.

Your index page…What it showsBuild warning
uses a home component, or sets home: falseIts own contentNone
sets home frontmatterIts own content — home is ignoredYes — home is ignored
has no content of its ownAn empty pageYes — the page is empty

home: false isn't deprecated — it's harmless to keep, and the page shows what you wrote either way.

Since 16 November 2026

Since 16 November 2026, doc engine v2 no longer draws the generated home. Builds never fail because of it:

•
Every v2 index.mdx renders as its own content, in the frame its layout picks — the normal frame by default, or layout: wide for the full-width frame.
•
home frontmatter is ignored, with a build warning — never an error.
•
An index page with no content of its own still builds, with a warning that it's empty.
•
The index's sidebar section shows as a normal header tab.
•
appearance.layout.home — in syntext.json, project settings or an organization theme — is ignored with a warning, and the home blocks follow the preset.

To get back the look the generated home gave you, convert: Appearance › Convert home to content in the dashboard, or stx migrate — see Moving off the generated home. Sites not on doc engine v2 are unaffected.

A v2 site with no index page at all has no home: / sends readers to the first page of your navigation, and so does each translation's root (/fr/) when that language has no index of its own. A page or redirect of your own at / wins.

Moving off the generated home

•
Dashboard — the deprecation notice in Appearance has Convert home to content. It previews the new index.mdx as a diff, with a note for anything it can't carry over, then commits it or opens a pull request (admins; a commit needs deploy rights). Projects without a repository get the components to copy into index.mdx. It writes the blocks your generated home showed, in your preset's order.
•
CLI — stx migrate (stx 0.9.0 and later) writes the same components into docs/index.mdx, using your last build's site data when you're logged in.
•
API — Convert the Home to Content returns the same preview, or commits it or opens a pull request.
•
By hand — write the components into docs/index.mdx as above, delete home from its frontmatter and set layout: wide for the same frame. Or add home: false to show only the page.

A few things the generated home drew have no component: the example-answer card of the Ask block, Orbit's Agent tile, and changelog items written into home (<LatestUpdates> reads your changelog page instead).

Deprecated: home frontmatter

On doc engine v2, home no longer builds anything: since 16 November 2026 it's ignored with a warning — never a build failure — and the page shows its own content. v1 sites ignore it too. Convert it to keep its blocks. For reference, this is the shape it took:

yaml
---
title: Acme Docs
home:
hero:
title: Build with Acme
description: Payments, payouts and webhooks in one API.
actions:
- { label: Quickstart, href: /quickstart }
install: npm install @acme/sdk
blocks:
- type: quickstart
- type: cards
- type: support
title: Need a hand?
text: Our team answers within a day.
cta: { label: Contact support, href: https://acme.com/support }
---

hero takes title, description, actions (up to 6 { label, href }) and install. blocks lists quickstart, cards, api, sdks, changelog, popular, commands, ask and support — when set, only those appear, in your order; whatever a block leaves out is filled from your site. Each maps to a component: <Hero title>, <QuickStart>, <SectionCards>, <ApiGroups>, <SdkList>, <LatestUpdates>, <PopularPages>, <CommandList>, <SearchBar size="lg"> and <SupportCard>. The page's own body renders below the blocks. An unknown block type or field is dropped with a "did you mean" build warning:

text
home.blocks[1].type: unknown block "card", ignored. Expected one of quickstart, cards, api, sdks, changelog, popular, commands, ask, support. Did you mean "cards"?

Deprecated keys

These keys still work, but are deprecated. The build log warns with the file and line and the replacement, and after the notice window the build fails with the exact fix. stx migrate rewrites both.

DeprecatedUse insteadNotes
noIndexnoindexWhen both are set, noindex is kept and noIndex removed
fullWidth: truelayout: full-widthfullWidth: false is simply deleted. When layout is already set, it's kept
home (index page)The home components in the page bodyv2 only. The generated home ended on 16 November 2026: home is ignored with a warning, never an error. home: false isn't deprecated

Complete Example

yaml
---
# Core metadata
title: Create User
description: Create a new user account via the REST API.
sidebarTitle: Create user
tag: New
# Protocol (for API pages)
protocol: rest
method: POST
endpoint: /v1/users
# Layout
layout: default
toc: true
sidebar: true
# SEO
ogImage: /images/api/create-user-og.png
# Features
feedback: true
editUrl: https://github.com/acme/docs/edit/main/docs/api/create-user.mdx
---
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext