syntext.json
Complete reference for the Syntext configuration file.
The syntext.json file is the central configuration for your documentation site. It controls navigation, theming, integrations, and more.
Syntext reads the first of syntext.json, syntext.yaml, syntext.yml or syntext.config.json it finds at the repository root. If that file can't be parsed, or doesn't hold an object, the build fails with the file name and the parser's message, for example Build failed: syntext.json is not valid JSON: JSON Parse error: Expected '}'. Fix the file and push again; the live site keeps its previous deploy until then.
Basic Structure
$schema
Points your editor at the published JSON Schema for this file, so VS Code, JetBrains IDEs and other JSON-aware editors autocomplete every key, show its description, and underline a misspelt key or a value outside its allowed set as you type:
stx init writes this line first in every new project. The build ignores the
key. The schema is generated from the same definition the build validates
against, so the editor, stx check and the build agree. It's
also served at https://api.syntext.dev/v1/schema/syntext.json — see
Get syntext.json Schema.
In syntext.yml, point the YAML language server at it instead:
Core fields
No key is required. Without navigation the folder structure is the sidebar
(see Navigation).
name
The project name. Displayed in the header and browser tab.
navigation
Defines the sidebar navigation structure. See Navigation for details.
locale
The document language for the whole site, as a BCP-47 tag. Written to every
page's <html lang>, and the writing direction is derived from it.
language is the deprecated name of this key — see
Deprecated and renamed keys.
Defaults to en. Arabic, Hebrew, Persian, Urdu, Pashto, Kurdish, Divehi,
Yiddish and the other right-to-left languages produce dir="rtl", and the page
layout mirrors: the navigation sidebar moves to the right, the table of
contents to the left, indents and borders swap ends, and the arrows that point
flip. Code blocks, URLs and endpoint paths stay left to right inside
right-to-left prose.
A single page can override this with lang in its frontmatter, and force a
direction with dir. See
Page frontmatter.
i18n
The languages this site publishes. Renders the language switcher in the top bar
and the hreflang alternates in every page's <head>. On doc engine v2 the
language menu sits in the header, next to the version control, and in the phone
and tablet drawer.
| Key | Default | Description |
|---|---|---|
defaultLocale | "en" | The language your source pages are written in. Served at its existing URLs, with no prefix |
locales | [] | The other languages you publish, in the order they should be listed. Each is served under /{locale}/… |
label | "Language" | The switcher's accessible name |
sourceLocale and locale (for defaultLocale) and targetLocales (for
locales) — the spellings the translation add-on stored — still work, but are
deprecated.
Nothing is rendered unless at least one locale other than the default is named, so a site without this key, with an empty list, or with a list containing only the default is completely unaffected. Values that are not plausible BCP-47 tags are dropped.
See Translated documentation for what readers get and how the URLs are laid out.
How values are read
syntext.json is read as JSON, and syntext.yml / syntext.yaml as YAML. The
three carry exactly the same schema — every key on this page works in either
format, in the build, stx check, the web editor and the
appearance editor. When more than one exists, the first of syntext.json,
syntext.yaml, syntext.yml is used.
syntext.config.json is the old file name. It's still read when none of the
three exists, but it's deprecated;
stx migrate renames it.
Unknown keys and values
A key this page doesn't define is ignored, and the build log, stx check and
the web editor warn with the line and the closest valid key. A value outside a
key's allowed set is reported the same way:
Unknown keys follow the deprecation policy
(code config.unknown-key): today they're warnings.
Wrong types
Where a single
piece of text is expected — name, favicon, search.placeholder, a logo's
suffix — a number or true/false is used as written, and a list or nested
block is treated as if the key were absent, so the documented default applies.
A key with an unexpected value therefore costs you that one setting. It does not fail the build, and it does not affect any other page on the site.
Site Metadata
description
Meta description for SEO and social previews. It is the fallback: a page
that sets its own frontmatter description keeps it, and a page that sets
none uses this instead of shipping an empty tag.
github
Link to your GitHub repository. Shown in the header.
socialLinks
Social media links displayed in the header.
Supported platforms: GitHub, X, Discord, LinkedIn, YouTube, Slack.
Doc engine v2 shows GitHub, X (X or Twitter) and LinkedIn only, as icons in
the footer, and only when footer.columns is set.
seo.ogImage
Social card image used for link previews (Open Graph and Twitter cards). Shown when your docs are shared on X, Slack, Discord, LinkedIn, and other platforms.
Relative paths resolve against your site URL. Absolute URLs are used as-is. Recommended size: 1200×630 pixels. When set, pages emit og:image, twitter:image, and a summary_large_image Twitter card.
A top-level ogImage is the deprecated spelling — use seo.ogImage.
Branding
logo
Logo images for light and dark modes.
Or a single logo:
Brand lockup
Two optional keys control how the logo sits beside the site name.
| Key | Description |
|---|---|
type | "mark" (default) keeps the site name beside the logo. "wordmark" means the image already contains the name, so the logo is shown alone, with no site-name text next to it |
suffix | A muted lowercase word after the brand, such as docs. On API reference pages it replaces the uppercase DOCS chip. v1 only — doc engine v2 ignores it |
type: "wordmark" works on doc engine v2 sites too: every
header style, the phone and tablet bars, the navigation drawer and the footer
show the logo alone. It's ignored when no logo image is configured — otherwise
the header would have nothing to show — and the site name stays.
Use a path on your site (/logo.svg), an http:// or https:// URL, or an
image data: URL for light, dark and favicon. The
appearance editor writes name, logo
({ light, dark, type }) and favicon for you, pointing at files you upload
there, and refuses any other kind of URL. With no logo or favicon set —
here or in a hosted project's settings — the site uses the Syntext mark.
favicon
Favicon URL.
Only a string is used. An object of sizes is accepted by the schema but ignored.
colors (deprecated)
Deprecated. Each key has a replacement — see the table below.
stx migrate moves them for you.
Brand colors.
| Property | Maps to token | Description |
|---|---|---|
primary | accent (+ derived hover/subtle/muted ramp) | Main brand color (links, buttons, active states) |
accent | accent-strong | Stronger accent — link hover, emphasis |
background | bg-page | Page background |
This is legacy shorthand, kept for compatibility. It is applied after
themeOverrides, so an existing site never changes appearance because a preset
was introduced. For new sites prefer appearance.accent on
doc engine v2, or themeOverrides, which reaches every
token rather than three.
| Deprecated | Use instead |
|---|---|
colors.primary | appearance.accent — v2 only (see below) |
colors.accent | themeOverrides.colors.light.accent-strong and themeOverrides.colors.dark.accent-strong |
colors.background | themeOverrides.colors.light.bg-page and themeOverrides.colors.dark.bg-page |
appearance.accent is read only by the doc engine v2 renderer, and adding
appearance switches a site to v2. So on a site that still renders with v1,
colors.primary stays a warning — it never fails the build — until the site
moves to v2. On a v2 site, colors.primary sets the accent for both modes and
wins over appearance.accent (see Precedence).
Navigation
tabs
Top-level navigation tabs.
A tab can also be just its name: "tabs": ["Guides", "API"].
On doc engine v2 sites:
url is / stands for your home page, which the logo already
links to, so it is not shown as a section when you have other tabs. Its
pages still have their sidebar, and the home's section index lists the other
tabs only. A site whose only tab is / keeps it. When your index.mdx is
built from home components and keeps
the normal frame (no layout: wide), it has a sidebar, so its section is
shown as a tab like any other.icon is used where a preset draws section icons (Orbit's navigation column, and the dock nav). Any
icon name works, plus guides, component, api,
sdk, cli and changelog; anything else falls back to an icon picked from
the tab's name, then a book.anchors
Doc engine v1 only — v2 doesn't render anchors. Quick links, rendered at the top of the navigation sidebar — the first thing below the header search — and repeated in the mobile navigation drawer so they are reachable on a phone.
Each entry takes name, url and an optional icon from the same icon set
Cards use; an icon name the set does not know renders
nothing and leaves the label alone. An entry missing name or url is
skipped. External links open in a new tab with rel="noopener noreferrer".
OpenAPI Integration
openapi
Path or URL to your OpenAPI 3.x specification. At build time, Syntext parses every listed spec and generates one MDX endpoint page per operation plus an overview page per spec — directly into your docs tree, alongside your hand-written pages.
Remote URL (fetched fresh on every build):
A remote spec URL must be http or https on a public host. Private and
local addresses are refused, and the build log says which URL it couldn't
fetch. $ref
pointers inside a spec are resolved within that document only — a $ref to
a file path or another URL is not followed, so a multi-file spec needs to be
bundled before it is committed or served.
Multiple specs with slug prefixes (microservices, one spec per resource group):
Multiple base URLs (production + sandbox) for the API playground — declare them once at the top level of syntext.json with baseUrls:
Plain strings work too ("baseUrls": ["https://api.example.com"]). Add "x-syntext-sandbox": true to a server object to mark it as the sandbox the agent mode assistant's API runs go to; without a marked server, runs go to the first server, your live API — see Sandbox servers for assistant runs. If one spec needs different hosts, add a servers array to that openapi entry — it overrides baseUrls for that spec only:
Authorization and extra headers for the API playground can also be declared at the top level — auth sets which header (or query parameter) carries credentials, and headers adds header parameters to every generated endpoint page:
auth is how your API authenticates: the Try it console's credential field and the generated request samples' auth header follow it. It takes one scheme, a list of alternatives, or "none", with the same fields as page auth: type (bearer, basic, apiKey, oauth2, openIdConnect), name, in ("header", "query" or "cookie"), label, description, bearerFormat (such as "JWT") and prefix. A page's own auth frontmatter wins, so an endpoint that differs (a public one: auth: none) declares it there. With no auth anywhere, pages show no credential: no Authorization field and no auth header in samples. For a session-token API:
The v1 form, { "name": "Api-Key" } with optional label, in and prefix, still works. headers entries accept name, type, required, and description — plain strings work as shorthand ("headers": ["X-Idempotency-Key"]). Both keys can also be set on an individual openapi entry to override the top level for that spec only.
How generation works:
prefix, each endpoint page lands at {prefix}/{method}-{path} (e.g. api-reference/users/get-v1-users-user-id) and the spec's overview at {prefix}/overview. Slugs are derived from the HTTP method and path — never from operationId — so URLs stay stable even if you rename operations. Without a prefix, the generator's default slugs are used.servers array on an openapi entry > top-level baseUrls > the spec's own servers list. Top-level baseUrls also applies to hand-authored REST pages (per-page servers frontmatter still wins).auth frontmatter > auth/headers on an openapi entry > top-level auth/headers > the spec's own security and securitySchemes. An operation with security: [] stays public whatever the config says. Top-level auth also applies to hand-authored REST pages without their own auth frontmatter.API overview sections
On doc engine v2, a spec's generated
API overview can end
with Rate limits, Pagination and SDKs sections, after Errors and
before Endpoints. A spec says little about these, so you describe them in
the top-level api object. The same sections appear on the overview of every
spec. v1 sites ignore them.
Each section comes from api first, then from your spec where it has
something real to offer — api wins section by section, never field by field:
| Section | From api | Otherwise, from the spec |
|---|---|---|
| Rate limits | rateLimits | The rate-limit response headers your operations declare, as the header table only |
| Pagination | pagination | The request parameters named by x-speakeasy-pagination or x-fern-pagination |
| SDKs | sdks | Nothing — no OpenAPI convention lists installable SDKs |
A section with nothing to show is left out. The description of every
section is a paragraph under its heading: text in backticks becomes inline
code and line breaks are kept.
rateLimits
| Key | Type | Description |
|---|---|---|
description | string | Paragraph under Rate limits |
tiers | array | One row per plan: name is the first column (Plan), and each key of limits becomes a column, with its number or text as the cell. A plan that leaves a column out shows — |
headers | array | The Header / Meaning table. Each entry is a header name, or { "name", "description" } |
rateLimits needs tiers or headers; with neither, it's ignored and the
spec's headers are used. Once it has either, the spec's headers are not added
— list them in headers if you want both.
pagination
| Key | Type | Description |
|---|---|---|
description | string | Paragraph under Pagination |
parameters | array | Shown as a field list. Each entry takes name (required), type (default string), in (default query), default and description |
example | string or JSON | A page of results, shown as a JSON code block. A string is shown as written; any other value is pretty-printed |
pagination needs parameters or example; with neither, it's ignored and
the spec's pagination parameters are used.
sdks
An array of SDK cards, or { "description": "…", "items": [ … ] } to add a
paragraph above them:
Each card takes name (required), install (the command shown on the card),
url (makes the card a link) and icon (default code). Cards sit up to
three to a row.
Entries without a name are skipped, in all three sections.
Because specs are read on every build, committing a spec change and deploying is all it takes to update your API reference — no separate import step. See the OpenAPI sync recipe.
api
API reference settings. Doc engine v2 only.
requestLanguages lists the languages of the generated request sample on endpoint pages, in tab order. Values: curl, javascript, typescript, node, python, python-httpx, go, ruby, php, java, csharp, rust, swift, kotlin and http. Default: ["curl", "javascript", "python", "go", "ruby", "php", "java", "csharp"]. It applies to pages generated from an OpenAPI spec and to hand-written endpoint pages — with or without examples of their own (see generateAlongsideAuthored below); a page's requestLanguages frontmatter overrides it. Copy as code in Try it lists these languages first, then the rest of the 15. Unknown values are reported by stx check and ignored.
Every sample is a complete program (imports, a client, the call) that sends the same request: the page's base URL (the order Try it uses: several servers in frontmatter, several baseUrls, then the page's baseUrl, its single server or the single site base URL; with none, the path alone), path parameters filled from their example or default (else {name}), query parameters that are required or have an example, a JSON body with Content-Type only when the page documents body parameters, and, only when auth is declared, a placeholder credential (<token>, <jwt> for bearerFormat: JWT, or <api-key>). With no auth declared, the samples carry no auth header.
generateAlongsideAuthored (boolean, default true) decides what a hand-written endpoint page with its own request example shows. With true, the authored tabs come first, exactly as written, followed by a generated tab for each requestLanguages language they leave out. The generated tabs send the author's request, read from its first cURL command: method, URL, headers and body, -F multipart parts with @file uploads, --data-binary files and raw text, with $NAME environment references carried into each language. Without a usable cURL they're built from the page's ParamFields. With false, the authored example is shown alone. A page with no authored request example always gets the generated one. Precedence: page generateAlongsideAuthored frontmatter > api.generateAlongsideAuthored > true.
Uploads work in every language: multipart forms with files, a raw file as the whole body, and raw text bodies are written out in all 15.
Versioning
versioning
Enable versioned documentation. Each version builds from its own git ref (tag > branch > label); the default version serves at the site root, others under /{label}/. Two or more versions render a switcher in the doc-site header.
See Versioning for all fields, URL behavior, deprecation banners, and version-scoped search.
Multi-version builds need the Pro plan or higher. On lower plans only the default version is built, and the build log says so — see Versioning.
Theme Configuration
A theme is data, not code: pick a preset by name, then override individual tokens. Nothing needs to be forked to restyle a site.
theme
The preset — or organization theme, or v1 theme — the site starts from.
A doc engine v2 preset switches the site to the v2 renderer. Names are lowercase. See Presets and appearance.
| Preset | Fonts | Accent |
|---|---|---|
workbench | Geist + Geist Mono | #E4512B |
paper | Figtree + IBM Plex Mono | #0E7A63 |
console | IBM Plex Sans + JetBrains Mono (dark first) | #3DDC97 |
atlas | Public Sans + Roboto Mono | #2457D6 |
plain | Hanken Grotesk + Fira Code | #6D28D9 |
orbit | Manrope + DM Mono | #4F46E5 |
grid | Inter Tight + IBM Plex Mono | #E11D48 |
margin | Instrument Sans + Red Hat Mono | #0E7490 |
The two v1 themes keep a site on the v1 renderer:
| v1 theme | Description |
|---|---|
default | Syntext's built-in look — Inter + JetBrains Mono, zinc neutrals, blue accent |
gravv | Bricolage Grotesque display + Geist Mono body, green accent, dark code surfaces in both modes |
An unknown name falls back to default and logs a warning in the build log — it
never fails the build.
theme can also name an organization theme — a saved, versioned look
shared across your organization's projects. It also switches the site to v2:
| Value | Meaning |
|---|---|
"@acme/brand" | The brand theme of the organization with the slug acme, latest version. A new version reaches this site on its next build |
"@acme/brand@3" | Version 3 of that theme, pinned. New versions don't change the site until you change the number |
A project can only use its own organization's themes. A reference to another organization's theme, a theme that doesn't exist or a version that doesn't exist is a build-log warning, and the site builds with the preset instead — it never fails the build. The build log names the version it used:
See Organization themes.
themeOverrides
Per-token overrides applied on top of the preset. Every level is optional, so you can change one colour without restating the theme.
Fonts take three roles — display (headings), body, and mono. A bare
string sets the family; an object can also set weights, fallback and
webfont (google, system or self-hosted). Families
are fetched from Google Fonts automatically, de-duplicated when one family serves
two roles.
Colours are a light/dark pair of semantic tokens (accent, bg-page,
bg-sidebar, content-primary, border, method-get, syntax-keyword, …).
Syntax colours also drive code highlighting, which is baked at build time rather
than applied with CSS.
Typography covers named styles (display-h1, heading-h2, body-md,
nav-item, eyebrow, code-sm, …). All values are in px, matching Figma.
apiTypography takes the same style names and applies them to API reference
pages only (v1).
Shadows — shadow.light and shadow.dark, each with sm, md and lg as
CSS shadow strings.
Unknown token names are ignored with a build warning rather than failing.
Values are CSS values, not arbitrary CSS. A colour, shadow or font value is
emitted as a single declaration in the generated stylesheet, and the build
strips anything that would end that declaration or reach outside it — ;,
{, }, <, >, @, :, !, comment markers and url(. Ordinary values
are unaffected: hex, rgb()/rgba(), hsl(), color-mix(), gradients and
multi-part shadows all pass through exactly as written. Font families are
restricted to name characters, and typography sizes, weights, letter-spacing
and radii must be numbers. If you need styling that a token cannot express,
use a stylesheet rather than smuggling it through a token.
See Theming for the full token list.
themeOverrides on doc engine v2
On a v2 site, themeOverrides applies on top of
appearance, using the same v1 token names. These tokens change v2 pages:
| themeOverrides key | What it sets on a v2 page |
|---|---|
colors.{mode}.accent | The accent for that mode — every accent shade is derived from it, as for appearance.accent |
colors.{mode}.content-primary, content-secondary, content-muted | Body text, secondary text, muted text |
colors.{mode}.bg-page | The page canvas and surface |
colors.{mode}.bg-subtle | Panels |
colors.{mode}.border, border-subtle | Lines and borders |
colors.{mode}.bg-code, content-code, border-code | Code block background, text and border |
colors.{mode}.accent-strong | Link text |
colors.{mode}.accent-subtle | The accent tint |
colors.{mode}.on-accent | Text on accent fills |
colors.{mode}.status-success, status-success-bg, status-warning, status-warning-bg, status-warning-text, status-error, status-info, status-info-bg, status-info-text | Status colours |
colors.{mode}.syntax-* | Code highlighting colours, as on v1 |
fonts.display, fonts.body, fonts.mono | Heading, body and code fonts |
typography.body-md.size, typography.body-md.lineHeight | Body text size (10–32px) and line height (1–4) |
typography.display-h1.size, typography.display-h1.weight | Page title size (16–96px) and weight (100–900) |
radius.sm, radius.md, radius.lg | The corner scale (0–64px) |
Every other v1 token has no v2 equivalent and is ignored on v2 pages:
content-inverse, content-code-inline, bg-code-inline, bg-sidebar,
bg-raised, bg-header, bg-code-header, accent-hover, accent-muted,
accent-fill, cta-bg, cta-fg, hero-card-bg, hero-card-fg, the
param-* and method-* tokens, scrollbar, and every typography style other
than the four values above. On v2 a colour must be hex, rgb() or hsl();
anything else is skipped with a build-log warning.
appearance
Layout and component choices for the doc engine v2 renderer. A
preset sets a starting value for every field; appearance
overrides any of them. Every field is optional, and any switch combines with any
preset.
Adding an appearance block opts the site in to v2, even when theme names a
v1 theme or is left out. With no v2 preset in theme, the starting preset is
workbench. See Opting in.
Top-level keys:
| Key | Allowed values | Default |
|---|---|---|
accent | A hex colour ("#0E7A63", 3 or 6 digits), or { "light": "…", "dark": "…" } to set each mode on its own | The preset's accent |
mode | light, dark, system | The preset's mode (dark for Console, light for the rest) |
fonts | { "heading", "body", "mono" } — font family names | The preset's fonts |
size | 15, 16, 17 (body text, px) | The preset's size |
radius | none, small, medium, large | The preset's radius |
density | comfortable, compact | comfortable |
width | contained, full | contained |
toggle | true, false — the light/dark toggle | true |
illustrations | true, false | true |
layout | An object of layout switches (below) | The preset's |
components | An object of component switches (below) | The preset's |
mode sets the colour mode a first-time reader sees; system follows their
operating system. A reader who has picked a mode with the toggle keeps their
choice.
Every field changes every v2 page — guide, API, search, /ask and the
404 page:
accent — one colour for both modes, or { "light", "dark" }. Link
colour, tints, hover and the text on accent fills are all derived from it
per mode, the way the preset derives its own. Each mode's accent is checked
for contrast on that mode's page background — link text needs 4.5:1,
accent fills (buttons, active states) need 3:1. A miss is a build-log
warning with the nearest shade that passes; it never fails the build, and
your colour is kept:
The appearance editor runs the same
checks as you pick, and stx check --explain appearance prints them.
fonts — any Google Fonts family by name.
Only the three families in use are loaded. A heading font different from the
body font is used for every heading. System families (system-ui, Arial,
Helvetica, Georgia, Menlo, Consolas, SF Mono and the like) are not
fetched.size — the body text size. Headings scale with the preset.radius — the corner scale: small (3/4/6px), medium (5/8/10px),
large (10/16/22px). none squares every corner, including the ones a
preset draws at a fixed size (Paper's sheet, nav pills); fully rounded pills
and circles stay round.density — compact tightens the reading rhythm one step: line height
−0.1, a header 8px shorter, less padding above and below the content, and
tighter sidebar rows. Text sizes don't change.width — contained stops the layout growing at 1440px and centres it
on wider screens; header bars and the footer keep their full-width
background. full runs the layout edge to edge at every width. The reading
column keeps its width either way.toggle — false removes the light/dark switch everywhere and pins the
site to mode. A reader's stored choice is ignored, since they'd have no
way to change it back. With mode: "system" the site still follows the
reader's operating system.illustrations — false leaves out every illustration: empty states,
the 404 page, the home and playground art.Layout switches (appearance.layout):
| Switch | Allowed values |
|---|---|
shell | bordered, sheet, enterprise, minimal, floating, grid, focus |
header | command, pill, tabs, mega, simple, island, index, path |
home | Deprecated. command, pill, tabs, mega, simple, island, index, path — the home layout the home components were drawn in. Default: the preset's own home. Ignored with a warning since 16 November 2026, never an error; delete it |
nav | tree, pills, mono, chevrons, plain, dock, chapters, overlay, sections |
toc | progress, pills, dots, rule, plain, float, ruler, ticks |
groups | collapsible, open. collapsible lets readers fold groups and nested groups from the chevron on their heading. Every group and nested group starts folded except the ones holding the current page, so readers always see where they are. What a reader opens or folds stays that way as they move between pages, and opening a page in a folded group opens it. open removes folding. Every preset starts collapsible |
headerBackground | solid, transparent. What sits behind the header as the page scrolls. solid keeps a band behind it, so text stops at its lower edge. transparent lets the page scroll behind the header: a floating header (Orbit's island) keeps its own background and shadow and the content shows around it; a full-width header bar turns frosted, so the content shows through it blurred. Default: transparent with the island header (Orbit), solid with every other — so changing header to island makes it float too, unless you set headerBackground |
Which preset uses each nav value:
| nav | Preset | Notes |
|---|---|---|
tree | Workbench | |
pills | Paper | |
mono | Console | |
chevrons | Atlas | Groups fold with a chevron |
plain | Plain | |
chapters | Grid | Every group but the current one starts folded |
overlay | Margin | |
sections | Orbit | One section column; each page is led by its frontmatter icon — file-text when it has none, and an endpoint keeps its method |
dock | — | No preset uses it by default |
See Presets to compare them.
nav: "collapsible" is still accepted as an older spelling of chevrons, but it's deprecated.
Each switch changes only the region it names. Anything no switch names keeps the preset's look:
| Switch | Its region |
|---|---|
shell | The page frame — layout grid, columns and surfaces, and where blocks sit in the column |
header | The header bar at every width — on phones too, with its section drawer — and its brand, links, search box, call-to-action and Docs/Agent switch |
home | Deprecated and ignored with a warning — the home components follow the preset |
nav | The sidebar |
toc | The on-page table of contents |
So "header": "pill" on Console gives Console a pill header and nothing else:
its home, search dialog, menus, chat, buttons, sidebar and cards stay
Console's. A preset's home blocks are drawn for its own header value —
Workbench's is command, Paper's pill, and so on (see
Presets). The home switch that changed them is
deprecated (config.layout-home):
since 16 November 2026, set in syntext.json, project settings or an
organization theme, it is ignored with a warning (never an error) and the home
blocks follow the preset — see Since 16 November 2026. Component switches work the same way: cards
styles cards only, not accordions, expandables, frames, badges or changelog
entries.
Component switches (appearance.components):
| Switch | Allowed values |
|---|---|
callout | labelcol, tag, strip, box, soft, float, cell, sidenote |
steps | rail, cards, prompt, procedure, list, stack, cells, margin |
code | dark, light, inset, navy, plain, float, cell, bleed |
cards | bordered, tile, outline, accent, plain, bento, cell, rows |
tabs | underline, pill, mono, boxed, text, segment, cells |
api | spec, card, term, boxed, plain, split, grid, stacked |
codeRadius | site, none, small, medium, large. The corners of code blocks, code tabs, request and response panels on API pages, and the copy and ask buttons. site (default) keeps the corners of the code style, which follow radius and the preset; the others set one size for every code block, whatever radius is |
Each code style brings its own colours as well as its shape, on every preset:
dark, float and bleed are dark blocks in both modes, navy is a navy
block, and light, inset, plain and cell are light blocks on a light
page and dark ones in dark mode. Syntax colours match the block. A preset's own
style keeps the preset's exact colours.
Each preset's values for every switch are listed on Presets.
Opting in to v2
v2 is opt-in. A site renders with v2 when any of these is true:
theme names a v2 preset ("theme": "workbench")theme names an organization theme ("theme": "@acme/brand")syntext.json has an appearance blockEvery other site — including "theme": "default", "theme": "gravv" or no
theme at all — keeps the v1 renderer and its output is unchanged. A v2 build
logs which preset it used, for example Appearance: workbench preset (doc engine v2).
A site whose theme is an organization theme renders with that theme's
preset, then the theme's appearance, then the site's own appearance on top.
If the theme can't be resolved, the site renders with Workbench and its own
appearance, and the build log says why.
Unknown values
A bad appearance value never fails the build. The build log gets a warning
naming the field and the allowed values, with a suggestion when one is close,
and the field keeps the value it would otherwise have had:
On a v2 site, an unknown theme name is reported the same way and falls back to
Workbench — "theme": "Paper" suggests "paper".
Precedence
Resolution order, lowest priority first:
default presetthemethemeOverridescolors blockcolors is applied last on purpose, so an existing site never changes
appearance because a preset or override was introduced.
On a v2 site there are two chains. The appearance — every field in
appearance — resolves first, lowest priority first:
theme, the organization theme's preset,
or Workbenchtheme, mapped onto v2 — gravv sets accent #077155, layout.header: "tabs" and components.code: "inset", and keeps Workbench's command home; default changes nothingfeatures flags, for fields appearance leaves out — navStyle (split → header tabs, single → simple; the header only — the home follows the preset), sidebarStyle (collapsible → nav chevrons, flat → plain), codeBlockStyle (pill → code dark, panel → inset), shellWidth → width, themeToggle → toggleappearanceappearanceThen the tokens — the colours, fonts, sizes and corners v2 pages draw with — are set from that appearance and layered, lowest priority first:
themeOverridesthemeOverridescolors and fonts blocksSo on v2, colors.primary wins over appearance.accent, and a legacy fonts
block wins over themeOverrides.fonts — the reverse of v1, where an explicit
themeOverrides.fonts beats fonts. Both legacy blocks are
deprecated; move them into appearance to
avoid the surprise.
stx check --explain appearance prints every value with the step it came
from — see stx check.
fonts (deprecated)
Deprecated. On doc engine v2, use appearance.fonts (heading, body,
mono). On v1, use themeOverrides.fonts, which maps to the theme's
display / body / mono roles.
The old block is still honoured. On v1 it is folded into
themeOverrides.fonts — heading (or display) becomes display — and an
explicit themeOverrides.fonts always wins. On v2 it is applied last, so
it wins over both appearance.fonts and themeOverrides.fonts. A malformed
block is ignored rather than failing the build.
Moving fonts.* into appearance.fonts is a v2-only change, so on a site that
still renders with v1 these keys stay warnings and never fail the build — see
Deprecated and renamed keys.
codeTheme
Not currently applied. Syntax colours come from the theme's syntax-* tokens
(see themeOverrides.colors), because the highlighter bakes colours into the
HTML at build time and cannot be retargeted with CSS afterwards. This key is
accepted but has no effect.
Top Bar
Two keys control the trailing edge of the header.
| Key | Description |
|---|---|
topbarCta | The filled call-to-action button. On v1, omit it to keep the default "Get Started" link; set it to null to render no button at all. On doc engine v2 there is no default — the button shows only when both label and url are set |
topbarLinks | Plain-text links rendered before the CTA. Each entry needs both label and url; incomplete entries are skipped. On doc engine v2 they appear only in the company bar above the mega header (Atlas); other header styles don't show them |
Both apply to guide pages and API reference pages alike.
dashboardUrl has no effect. Use topbarLinks instead, which lets you name the
link.
Grouped top-bar links
A topbarLinks entry may carry links instead of url. It then renders as a
dropdown rather than a link, which is how you fit four or five destinations into
a header that has room for two:
| Key | Description |
|---|---|
label | The group name, shown in the bar with a chevron |
links | The destinations. Each needs label and url; description adds a second line under the label inside the menu |
Flat entries and groups mix freely, in whatever order you list them. A group
with no usable child is skipped rather than rendered as an empty menu, and a
url on a group itself is ignored — the label opens the menu, it does not
navigate.
The menu opens on click or Enter, closes on Escape or a click outside, and returns focus to the label it came from. It works with JavaScript disabled, at every viewport width, and in right-to-left layouts. Its contents also appear in the mobile menu, already expanded.
Adding groups changes nothing for a site that does not use them. A topbarLinks
list with no links array anywhere renders byte for byte as it did before this
key existed.
Feature Flags
The features block controls what a site contains — which optional controls
exist and which shape a component takes. Theme tokens control how a site is
painted; these control its structure. A design that omits a control can't be
expressed with colour alone.
| Flag | Default | Description |
|---|---|---|
playground | true | The "Try it" request playground on API reference pages |
copyPageActions | true | The "Copy page" control and its open-in-AI menu. Accepts true/false for both surfaces, or { "guides": true, "api": false } to differ |
sidebarMethodBadges | true | HTTP method chips beside API nav items |
codeLanguageSelector | "dropdown" | How the request panel offers languages. dropdown is a compact control in the panel header; tabs is a row inside that header; pills lifts the choice onto its own row above the panel. The pills row wraps, so it holds the full seven-language set at phone width without hiding any behind a scroll |
codeLanguageTabs | true | Deprecated, no-op — delete it. Never controlled anything — the panel only ever had a dropdown. Use codeLanguageSelector. stx migrate removes it |
aiAssistant | true | Assistant entry points — "Ask Assistant", agent mode |
parameterStyle | "table" | Deprecated, no-op — delete it. Parameters have only ever rendered as stacked rows; the table variant was never built, so neither value changes anything. stx migrate removes it |
endpointBarAction | "tryIt" | Trailing endpoint-bar control: tryIt, copy, or none |
codeBlockStyle | "pill" | Deprecated — use appearance.components.code. Code block chrome: pill (floating rounded header) or panel (bordered header rail joined to the block) |
codeLineNumbers | false | A line-number gutter on source code blocks. The numbers are drawn by CSS, so Copy still copies the code alone. Request and response panels are excluded — a payload is not a listing — and a single-line fence gets no gutter, because it reads as a command |
panelLabels | "inline" | Where the request/response captions sit: inline (inside the panel header, beside the language selector) or above (a plain caption over the panel, leaving the header to the selector and copy control) |
copyControlStyle | "icon" | The panel copy action: icon (a square glyph button) or label (the word "Copy", becoming "Copied" on success) |
shellWidth | "contained" | Deprecated — use appearance.width. Page shell geometry: contained keeps a 2rem inset each side and centres the page once the window is wider than its reading width, so the text column never narrows as the window grows; full runs edge to edge so the sidebar starts at the viewport edge and columns are divided by rules |
themeToggle | true | Deprecated — use appearance.toggle. The light/dark toggle in the top bar. Set false for a design with no theme control — a visitor's stored preference still applies |
responseStyle | "schema" | How responses are presented: schema is a status table plus a per-status field tree, prose is a Returns heading carrying the success description from the spec |
endpointBarUrl | "path" | Whether the endpoint bar shows just the path, or full to prefix the OpenAPI server host |
apiSectionLabel | false | Show the page's section as an eyebrow above API reference titles. Guide pages always show one |
navStyle | "split" | Deprecated — use appearance.layout.header. Top bar rows: split puts the section tabs on a second row below the brand and actions, single pulls them up beside the brand for a one-row header. Below 1025px both settings render the same mobile chrome: a one-row header with the breadcrumb bar and its menu button beneath it |
sidebarStyle | "collapsible" | Deprecated — use appearance.layout.nav. API sidebar groups: collapsible (<details> disclosure per group) or flat (all items always visible under a plain label). flat removes the disclosure control entirely, so it applies only while the sidebar holds 20 entries or fewer; above that it falls back to collapsible so a long navigation can still be folded |
Every default reproduces the behaviour that shipped before these flags existed, so a site is unaffected until it opts out.
On doc engine v2 only playground, endpointBarAction (whether it's tryIt),
aiAssistant and the five deprecated style flags (through appearance) take
effect. The other flags shape v1 pages only.
navStyle, sidebarStyle, codeBlockStyle, shellWidth and themeToggle
are deprecated in favour of appearance
(layout.header, layout.nav, components.code, width, toggle). They
keep working on v1 — on a v1 site they stay warnings and never fail the
build — and on v2 they fill in any field appearance leaves out (see
Precedence).
copyPageActions is per-surface because designs commonly differ — a guide page
carries the control while a dense endpoint page does not:
A surface you leave out keeps its default.
aiAssistant is deliberately independent of copyPageActions — the copy menu is
a page action that happens to include AI destinations, whereas aiAssistant is
the assistant itself. You can drop the menu and keep the assistant.
Setting playground: false implicitly drops a tryIt action, since the button
would have nothing to open. Asking for tryIt explicitly while the playground is
off logs a warning and falls back to copy.
Unknown flags and wrong value types are ignored with a build warning.
Custom Code
customCSS
Syntext does not apply customCSS (or customJS). Put your CSS in
_syntext/*.css in your docs folder instead — up to 50 KB, loaded after the
theme on every page — see Custom code from your docs.
You can also paste it under Integrations › Custom code › Override (advanced)
(Starter plan and up) or send it with PUT /v1/projects/{projectId}/custom-scripts
(customCss). See Custom CSS for the variables and hooks
to style doc engine v2 sites with.
Path to custom CSS file.
scripts
Syntext does not apply scripts; no custom script is injected into a built page
from this key. Put scripts in _syntext/*.js and head tags in
_syntext/head.html in your docs folder instead, and turn on Scripts from your
docs / Head tags from your docs under Integrations › Custom code — see
Custom code from your docs. Pasted head and body
snippets still work under Override (advanced) — up to 10 per slot, 10 KB
each — or with PUT /v1/projects/{projectId}/custom-scripts.
Custom JavaScript files.
Site Features
banner
Top announcement bar, rendered above the header so it scrolls away with the page rather than taking height from the sticky header.
| Key | Type | Default | Description |
|---|---|---|---|
text | string | — | The announcement. Required; without it no bar is rendered |
link | string | — | Optional href — the whole announcement becomes the link |
dismissible | boolean | false | Show a close button |
A dismissal is remembered per reader, keyed to the announcement's text, so publishing a new announcement shows it again to everyone who dismissed the last one. With JavaScript off the bar still shows and the close button is hidden. The bar is not printed.
On doc engine v2 dismissible works the same way: the
close button appears only when it is true. Closing it hides the bar on every page of
the site, and the reader's browser remembers it per banner: change the text
or link and the new banner shows again. A closed banner is hidden before the
page first paints, so nothing below it moves. If you later set dismissible
back to false, the bar shows again to readers who had closed it. A
deprecated version's notice also sits in a bar
at the top of the page, but it has no close button and can't be dismissed.
search
Search configuration.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | false turns site search off for readers, on doc engine v1 and v2 sites. See Turning search off |
placeholder | string | "Search..." | Label on the header search button and the fallback text of an in-page <SearchBar>, on guide and API reference pages alike. Doc engine v1 only — v2 ignores it and uses its own label |
placeholder names the button in the header, not the input inside the Cmd+K
modal. Keep it short: in the v1 one-row header the
button narrows at 1440px and drops its label entirely at 1365px, so a long label
is the first thing to disappear.
Turning search off
search.enabled in syntext.json wins over the project setting. Only an
explicit false turns search off — leaving it out, or true, keeps search on.
With search off:
<SearchBar> in a page renders nothing.mode="search" box, they're left out. A suggestion chip without a link asks
the assistant.The site's search index is still built, so the public search API keeps working — the setting removes only the search readers see on the site.
status
A status line pinned to the bottom of the left sidebar — a dot plus a short
label, usually linking to a status page. On doc engine v2 it shows as a link at
the right of the mega header's top bar (Atlas) and in the home blocks that
show status, not in the sidebar.
| Key | Type | Description |
|---|---|---|
label | string | The text beside the dot. Required — without it nothing renders, url or not |
url | string | Optional destination. When set, the line becomes a link that opens in a new tab; when omitted it is plain text |
Omit status (or set it to null) for no status line — that is the default. The
line renders on guide and API reference pages alike, and only where a sidebar
exists, so pages using layout: centered or layout: full-width never show it.
On a phone or tablet the sidebar collapses into the menu, taking the status line with it, exactly as it does on a site with no status line.
The label is static text. Syntext does not poll your status page — update the label and rebuild if the wording needs to change.
ai
Not read — this key has no effect on your site. It is listed here only so the two keys that do work are easy to find:
aiAssistant feature flag.search.placeholder.Redirects
redirects
URL redirect rules.
Each entry takes:
| Field | Type | Description |
|---|---|---|
from | string | Path to redirect from. Normalized to a leading slash, no trailing slash |
to | string | Target — a site path or an absolute https:// URL |
status | number | HTTP status code (optional, defaults to 301) |
Mintlify-style { "source", "destination" } keys still work as aliases for from / to, but in syntext.json they're deprecated — stx migrate renames them.
For each literal redirect (no * or :param patterns), the build also generates a small noindex stub page at the old path so legacy URLs resolve on the live site. Real pages always win — a redirect whose from collides with an existing page is skipped, and stub pages are excluded from the sitemap.
Wildcard and :param patterns are recorded in the generated _redirects file but are not currently applied on Syntext-hosted sites — only literal redirects (which get stub pages) resolve on the live site. If a legacy URL must keep working, list it as a literal from/to entry.
_redirects.json file
In addition to the redirects key, the build looks for a standalone _redirects.json file at your docs root or repo root (docs root is checked first). It contains the same entry shape as a plain JSON array:
This is handy when migrating from a platform that exports redirects as a file — stx migrate writes one automatically.
Merge behavior:
syntext.json and _redirects.json are combined into one listfrom paths, the syntext.json entry wins_redirects.json is not valid JSON (or not a JSON array), the build logs a warning and ignores the file — the build still succeedsfrom or to are silently droppedFooter
On doc engine v1, every doc site renders a full-width footer band at the bottom of each page. By default it shows your social links (from socialLinks and github) alongside a "Powered by Syntext" credit that links to the Syntext dashboard at app.syntext.dev.
On doc engine v2 the footer appears only when footer.columns has entries. It shows your logo, GitHub, X and LinkedIn icons, a copyright line and a "Built with Syntext" link.
footer
Add footer.columns to upgrade to a rich footer with your logo, social icons, and grouped link columns — similar to what you'd find on a marketing site.
Each column takes:
| Field | Type | Description |
|---|---|---|
title | string | Column heading (optional) |
links | array | Links in the column — each needs a label and a url |
Behavior:
/guides/...) navigate within your doc site; absolute URLs (https://...) open in a new tablogo (light/dark aware), project name, and social icons automaticallyfooter entirely to keep the compact default footerDeprecated and renamed keys
These keys still work, but are deprecated. The build log, stx check
and the web editor warn with the file, the line and the replacement for your
value. After the notice window the build
fails with the exact fix. stx migrate rewrites them — in
JSON it keeps your formatting, in YAML your comments.
| Deprecated | Use instead | v2 only |
|---|---|---|
language | locale | |
ogImage (top level) | seo.ogImage | |
redirects[].source | redirects[].from | |
redirects[].destination | redirects[].to | |
i18n.sourceLocale, i18n.locale | i18n.defaultLocale | |
i18n.targetLocales | i18n.locales | |
syntext.config.json (the file) | syntext.json | |
colors.accent | themeOverrides.colors.light.accent-strong and .dark.accent-strong | |
colors.background | themeOverrides.colors.light.bg-page and .dark.bg-page | |
colors.primary | appearance.accent | Yes |
fonts.heading, fonts.display | appearance.fonts.heading | Yes |
fonts.body | appearance.fonts.body | Yes |
fonts.mono | appearance.fonts.mono | Yes |
features.navStyle | appearance.layout.header (split → tabs, single → simple) | Yes |
features.sidebarStyle | appearance.layout.nav (collapsible → chevrons, flat → plain) | Yes |
features.codeBlockStyle | appearance.components.code (pill → dark, panel → inset) | Yes |
features.shellWidth | appearance.width | Yes |
features.themeToggle | appearance.toggle | Yes |
appearance.layout.nav: "collapsible" | appearance.layout.nav: "chevrons" | |
appearance.layout.home | Nothing — delete it. Since 16 November 2026 it's ignored with a warning, never a build failure, and the home blocks follow the preset | Yes |
features.codeLanguageTabs | Nothing — delete it (use features.codeLanguageSelector) | |
features.parameterStyle | Nothing — delete it |
v2 only keys move a value into appearance, which only the doc engine v2
renderer reads — and adding appearance switches the site to v2. On a site
that still renders with v1 they stay warnings forever; they never fail the
build. stx migrate holds them back unless you pass --v2.
Every deprecated form, including frontmatter and MDX, is listed on Deprecated syntax.
Other keys
| Key | Description |
|---|---|
projectId | The project this folder deploys to. Written by stx init --create and stx connect; read by the CLI only |
baseUrl | Base URL for the doc site's MCP tool manifest. Falls back to the MCP server integration's setting |
customJS | Accepted but not applied by hosted builds — see customCSS |