Frontmatter
Page-level configuration with YAML frontmatter.
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:
Common Fields
| Field | Type | Description |
|---|---|---|
title | string | Page title (required) |
description | string | Meta description for SEO |
sidebarTitle | string | Shorter label for the sidebar. See Navigation Fields |
tag | string | A short badge beside the page in the sidebar, such as New or Beta. See Sidebar badge |
hidden | boolean | Drop from the sidebar; still built and served. See Navigation Fields |
noindex | boolean | Keep the page out of search engines. See SEO Fields |
section | string | Which section — and so which header tab — the page belongs to. See Section and tab placement |
icon | string | Icon beside the page's sidebar entry. See Sidebar icons |
draft | boolean | Drop from the sidebar and mark noindex. See Navigation Fields |
sidebar | boolean | Show/hide the navigation sidebar. See Feature toggles |
toc | boolean | Show/hide the table of contents. See Feature toggles |
audience | string or list | Audience tags allowed to see the page. Gated pages leave navigation, search and the AI assistant for other visitors. See Audience gating |
css | string | A stylesheet for this page only, such as ./pricing.css. See Page stylesheet |
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:
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.
Sidebar icons
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.
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:
GET, POST
and so on already shows a method chip in that slot, and keeps it.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
How title and description Render
Beyond metadata, title and description can render as visible page content:
<h1> (no # Heading), the build synthesizes one from the frontmatter title, and renders description as a lead paragraph directly below it.<h1>, nothing is synthesized — the frontmatter values are used only for metadata (browser tab, sidebar, SEO).description, so you won't see it twice.This means both authoring styles work:
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:
| Layout | Description |
|---|---|
default | Three-column: sidebar + content + TOC |
centered | Single column, centered content — no sidebars; ideal for landing pages. Doc engine v1 only; v2 treats it as default |
full-width | Single column, full width — the sidebar and the on-this-page column both go |
landing | Keeps 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 |
wide | Doc 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:
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:
Solid Color
Gradient
Light and dark backgrounds
Give background an object to set a different value for each colour mode:
Background Image
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
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:
./pricing.css is relative to the page; /styles/pricing.css starts from the docs folder..css file inside your docs folder, at most 50KB. URLs aren't accepted._syntext/*.css and before pasted Custom CSS._syntext/*.css, and applies while CSS from your docs is on (the default).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:
| Field | Description |
|---|---|
description | Meta description (150-160 chars ideal) |
ogImage | Open Graph image for social sharing. Absolute, or site-relative (/images/og.png). Overrides the site-wide card from syntext.json |
noindex | true excludes the page from search engines (noindex, nofollow), on doc engine v1 and v2 sites. noIndex is the deprecated spelling |
canonical | Canonical URL for duplicate content. Replaces the generated canonical; og:url still names this page |
Navigation Fields
Control how the page appears in navigation:
| Field | Description |
|---|---|
sidebarTitle | Label to use in the sidebar instead of title |
tag | A short badge beside the page in the sidebar (New, Beta). At most 20 characters |
sidebarPosition | Sort order within the section — lower sorts higher |
hidden | Drop the page from the sidebar; it is still built and still served |
draft | Drop the page from the sidebar and mark it noindex; it is still served |
Sidebar badge
tag draws a small badge in your accent colour beside the page's sidebar
entry:
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.
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.
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:
| Field | Type | Description |
|---|---|---|
section | string | The section name, verbatim. Use the exact name of a header tab from tabs when you have one |
category | string | A coarser alias, mapped to a built-in section |
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 value | Section |
|---|---|
api, reference | API Reference |
sdk, client, library | SDKs |
changelog, releases | Changelog |
guide, tutorial | Guides |
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:
api/ or reference/ gives API Reference,
sdk/ / client/ / library/ gives SDKs, changelog/ / releases/ gives
Changelog. Everything else falls back to Guides.section, else category.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.navigation[].tab — a navigation group's tab always wins, provided the
name is one of your tabs. See Navigation.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.
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:
REST / HTTP
Renders a colored method badge (POST = green) and endpoint path.
REST pages also read three keys that configure the "Try it" console:
| Field | Description |
|---|---|
baseUrl | Base URL the console sends requests to |
servers | List 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 |
auth | How 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:
| Field | Description |
|---|---|
type | bearer (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) |
name | The header, query parameter or cookie that carries the credential. Required for apiKey; bearer defaults to Authorization |
in | header (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 |
label | What the console asks for, such as Session token or API key. Defaults: Bearer token, Username and password, the key's name |
description | One sentence under the field, such as where to get the credential |
bearerFormat | For example JWT. The samples then write <jwt> instead of <token> |
prefix | Written before the value. Defaults to "Bearer " for bearer, "Basic " for basic, nothing for a key |
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.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.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.-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.| Field | Description |
|---|---|
requestLanguages | Languages 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 |
generateAlongsideAuthored | true (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
GraphQL
gRPC
Event-Driven
Feature Toggles
Enable or disable page features:
| Field | Default | Description |
|---|---|---|
toc | true | Show the on-this-page table of contents |
sidebar | true | Show the left navigation sidebar. Doc engine v1 only |
feedback | true | Show 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.
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
| Field | Default | Description |
|---|---|---|
lang | site locale, else en | BCP-47 tag for this page, e.g. ar-EG |
dir | derived from lang | ltr or rtl, overriding what the language implies |
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:
| Component | What 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 shows | Build warning |
|---|---|---|
uses a home component, or sets home: false | Its own content | None |
sets home frontmatter | Its own content — home is ignored | Yes — home is ignored |
| has no content of its own | An empty page | Yes — 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:
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.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
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.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.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:
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:
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.
| Deprecated | Use instead | Notes |
|---|---|---|
noIndex | noindex | When both are set, noindex is kept and noIndex removed |
fullWidth: true | layout: full-width | fullWidth: false is simply deleted. When layout is already set, it's kept |
home (index page) | The home components in the page body | v2 only. The generated home ended on 16 November 2026: home is ignored with a warning, never an error. home: false isn't deprecated |