/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Configuration syntext.json

syntext.json

Complete reference for the Syntext configuration file.

49 min read

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

json
{
"$schema": "https://syntext.dev/schema/syntext.json",
"name": "My Docs",
"description": "Documentation for My Product",
"theme": "workbench",
"appearance": { "accent": "#6366F1" },
"navigation": [
{
"group": "Getting Started",
"pages": ["index", "getting-started"]
}
]
}

$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:

json
{
"$schema": "https://syntext.dev/schema/syntext.json"
}

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:

yaml
# yaml-language-server: $schema=https://syntext.dev/schema/syntext.json
name: My Docs

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.

json
{
"name": "My API Docs"
}

Defines the sidebar navigation structure. See Navigation for details.

json
{
"navigation": [
{
"group": "Getting Started",
"pages": ["index", "quickstart"]
}
]
}

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.

json
{
"locale": "ar-EG"
}

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.

json
{
"i18n": {
"defaultLocale": "en",
"locales": ["es", "fr", "de", "ja"],
"label": "Language"
}
}
KeyDefaultDescription
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.

yaml
# syntext.yml
name: My Docs
theme: paper
appearance:
accent: "#0E7A63"
navigation:
- group: Getting Started
pages: [index, quickstart]

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:

text
syntext.json:3: Unknown key "nmae" is ignored. Did you mean "name"?
"dropdwn" is not a valid features.codeLanguageSelector value. Use one of: dropdown, tabs, pills. Did you mean "dropdown"?

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.

json
{
"description": "Complete API documentation for MyProduct"
}

github

Link to your GitHub repository. Shown in the header.

json
{
"github": "https://github.com/yourorg/yourrepo"
}

Social media links displayed in the header.

json
{
"socialLinks": [
{ "platform": "GitHub", "url": "https://github.com/yourorg" },
{ "platform": "X", "url": "https://x.com/yourhandle" },
{ "platform": "Discord", "url": "https://discord.gg/yourserver" }
]
}

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.

json
{
"seo": {
"ogImage": "/og-card.png"
}
}

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 images for light and dark modes.

json
{
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg"
}
}

Or a single logo:

json
{
"logo": "/logo.svg"
}

Brand lockup

Two optional keys control how the logo sits beside the site name.

json
{
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg",
"type": "wordmark",
"suffix": "docs"
}
}
KeyDescription
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
suffixA 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.

json
{
"favicon": "/favicon.ico"
}

Only a string is used. An object of sizes is accepted by the schema but ignored.

colors (deprecated)

Warning

Deprecated. Each key has a replacement — see the table below. stx migrate moves them for you.

Brand colors.

json
{
"colors": {
"primary": "#6366F1",
"accent": "#2AC3DE",
"background": "#0F172A"
}
}
PropertyMaps to tokenDescription
primaryaccent (+ derived hover/subtle/muted ramp)Main brand color (links, buttons, active states)
accentaccent-strongStronger accent — link hover, emphasis
backgroundbg-pagePage background
Info

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.

DeprecatedUse instead
colors.primaryappearance.accent — v2 only (see below)
colors.accentthemeOverrides.colors.light.accent-strong and themeOverrides.colors.dark.accent-strong
colors.backgroundthemeOverrides.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).

tabs

Top-level navigation tabs.

json
{
"tabs": [
{ "name": "Guides", "url": "/guides", "icon": "book" },
{ "name": "API", "url": "/api-reference", "icon": "api" },
{ "name": "SDKs", "url": "/sdks", "icon": "code" }
]
}

A tab can also be just its name: "tabs": ["Guides", "API"].

On doc engine v2 sites:

•
A tab whose 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.
•
Any number of tabs fits. Where a preset's section control was drawn for a few short names (Workbench's sidebar switch, more than 3 tabs; Grid's header, more than 5) it becomes one menu showing the current section. Header tab rows stay on one line and scroll sideways. Paper, which draws no section control, gets the same menu at the top of its sidebar.

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".

json
{
"anchors": [
{ "name": "API Status", "url": "https://status.example.com", "icon": "signal" },
{ "name": "Support", "url": "mailto:support@example.com", "icon": "help" }
]
}

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.

json
{
"openapi": "./openapi.json"
}

Remote URL (fetched fresh on every build):

json
{
"openapi": "https://api.example.com/openapi.json"
}
Info

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):

json
{
"openapi": [
{ "path": "./specs/users.yaml", "prefix": "api-reference/users" },
{ "path": "./specs/orders.yaml", "prefix": "api-reference/orders" },
{ "url": "https://api.example.com/billing.json", "prefix": "api-reference/billing" }
]
}

Multiple base URLs (production + sandbox) for the API playground — declare them once at the top level of syntext.json with baseUrls:

json
{
"baseUrls": [
{ "url": "https://api.example.com", "description": "Production" },
{ "url": "https://sandbox.example.com", "description": "Sandbox" }
],
"openapi": [
{ "path": "./specs/users.yaml", "prefix": "api-reference/users" }
]
}

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:

json
{
"openapi": [
{
"path": "./specs/users.yaml",
"prefix": "api-reference/users",
"servers": [
{ "url": "https://users.example.com", "description": "Production" },
{ "url": "https://users-sandbox.example.com", "description": "Sandbox" }
]
}
]
}

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:

json
{
"auth": { "name": "Api-Key" },
"headers": [
{ "name": "X-Idempotency-Key", "required": true, "description": "Unique key to safely retry requests" }
],
"openapi": [
{ "path": "./specs/users.yaml", "prefix": "api-reference/users" }
]
}

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:

json
{
"auth": {
"type": "bearer",
"label": "Session token",
"bearerFormat": "JWT",
"description": "From the dashboard."
}
}

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:

•
Page slugs — with a 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.
•
Base URLs — when more than one base URL is declared, endpoint pages render a base-URL selector in the API playground, and code snippets plus Try-it requests follow the selected server. Precedence: a 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 & headers — the playground's Authorization field and extra header parameters follow the same chain: page 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.
•
Hand-authored pages always win — if a file already exists at a generated page's path, the generated page is skipped. Use this to hand-tune individual endpoint pages while keeping the rest generated.
•
Non-fatal errors — a spec that fails to parse or fetch logs a build warning and is skipped; the rest of the build continues.
•
Local paths must live inside the repository — paths that resolve outside the repo are rejected.

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.

json
{
"api": {
"rateLimits": {
"description": "Limits apply per API key. Every response reports what is left.",
"tiers": [
{ "name": "Free", "limits": { "Requests per minute": 60, "Builds per hour": 10 } },
{ "name": "Pro", "limits": { "Requests per minute": 600, "Builds per hour": 100 } }
],
"headers": [
{ "name": "X-RateLimit-Limit", "description": "Requests allowed this minute" },
"Retry-After"
]
},
"pagination": {
"description": "List endpoints return up to 20 items and a cursor for the next page.",
"parameters": [
{ "name": "limit", "type": "integer", "in": "query", "default": 20, "description": "Items per page, 1 to 100." },
{ "name": "cursor", "type": "string", "in": "query", "description": "The `nextCursor` of the previous page." }
],
"example": { "data": [], "nextCursor": "c_9f2kq1" }
},
"sdks": [
{ "name": "TypeScript", "install": "npm install @acme/sdk", "url": "/sdks/typescript" },
{ "name": "Python", "install": "pip install acme", "url": "/sdks/python" }
]
}
}

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:

SectionFrom apiOtherwise, from the spec
Rate limitsrateLimitsThe rate-limit response headers your operations declare, as the header table only
PaginationpaginationThe request parameters named by x-speakeasy-pagination or x-fern-pagination
SDKssdksNothing — 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

KeyTypeDescription
descriptionstringParagraph under Rate limits
tiersarrayOne 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 —
headersarrayThe 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

KeyTypeDescription
descriptionstringParagraph under Pagination
parametersarrayShown as a field list. Each entry takes name (required), type (default string), in (default query), default and description
examplestring or JSONA 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:

json
{
"api": {
"sdks": {
"description": "Official clients, generated from the same spec.",
"items": [
{ "name": "Go", "install": "go get github.com/syntext-dev/syntext-sdk-go", "url": "/sdks/go", "icon": "code" }
]
}
}
}

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.

Note

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.

json
{
"api": {
"requestLanguages": ["curl", "typescript", "python", "go", "rust", "http"],
"generateAlongsideAuthored": true
}
}

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.

json
{
"versioning": {
"versions": [
{ "label": "v3", "branch": "main", "default": true },
{ "label": "v2", "branch": "v2" },
{ "label": "v1", "branch": "v1", "deprecated": true }
]
}
}

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.

json
{
"theme": "workbench"
}

A doc engine v2 preset switches the site to the v2 renderer. Names are lowercase. See Presets and appearance.

PresetFontsAccent
workbenchGeist + Geist Mono#E4512B
paperFigtree + IBM Plex Mono#0E7A63
consoleIBM Plex Sans + JetBrains Mono (dark first)#3DDC97
atlasPublic Sans + Roboto Mono#2457D6
plainHanken Grotesk + Fira Code#6D28D9
orbitManrope + DM Mono#4F46E5
gridInter Tight + IBM Plex Mono#E11D48
marginInstrument Sans + Red Hat Mono#0E7490

The two v1 themes keep a site on the v1 renderer:

v1 themeDescription
defaultSyntext's built-in look — Inter + JetBrains Mono, zinc neutrals, blue accent
gravvBricolage 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:

ValueMeaning
"@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:

text
Organization theme @acme/brand: version 4 (latest)

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.

json
{
"theme": "default",
"themeOverrides": {
"fonts": {
"display": "Bricolage Grotesque",
"body": "Geist Mono",
"mono": "Geist Mono"
},
"colors": {
"light": { "accent": "#077155", "bg-page": "#ffffff" },
"dark": { "accent": "#15a07b", "bg-page": "#0b0d10" }
},
"typography": {
"display-h1": { "size": 34, "lineHeight": 42, "letterSpacing": -1.5, "weight": 600 }
},
"radius": { "sm": 8, "md": 12 }
}
}

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 keyWhat it sets on a v2 page
colors.{mode}.accentThe accent for that mode — every accent shade is derived from it, as for appearance.accent
colors.{mode}.content-primary, content-secondary, content-mutedBody text, secondary text, muted text
colors.{mode}.bg-pageThe page canvas and surface
colors.{mode}.bg-subtlePanels
colors.{mode}.border, border-subtleLines and borders
colors.{mode}.bg-code, content-code, border-codeCode block background, text and border
colors.{mode}.accent-strongLink text
colors.{mode}.accent-subtleThe accent tint
colors.{mode}.on-accentText 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-textStatus colours
colors.{mode}.syntax-*Code highlighting colours, as on v1
fonts.display, fonts.body, fonts.monoHeading, body and code fonts
typography.body-md.size, typography.body-md.lineHeightBody text size (10–32px) and line height (1–4)
typography.display-h1.size, typography.display-h1.weightPage title size (16–96px) and weight (100–900)
radius.sm, radius.md, radius.lgThe 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.

json
{
"theme": "paper",
"appearance": {
"accent": { "light": "#0E7A63", "dark": "#3DDC97" },
"mode": "system",
"layout": { "header": "command", "nav": "tree", "groups": "open" },
"components": { "code": "dark", "callout": "labelcol" }
}
}
Note

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:

KeyAllowed valuesDefault
accentA hex colour ("#0E7A63", 3 or 6 digits), or { "light": "…", "dark": "…" } to set each mode on its ownThe preset's accent
modelight, dark, systemThe preset's mode (dark for Console, light for the rest)
fonts{ "heading", "body", "mono" } — font family namesThe preset's fonts
size15, 16, 17 (body text, px)The preset's size
radiusnone, small, medium, largeThe preset's radius
densitycomfortable, compactcomfortable
widthcontained, fullcontained
toggletrue, false — the light/dark toggletrue
illustrationstrue, falsetrue
layoutAn object of layout switches (below)The preset's
componentsAn 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:

text
appearance.accent.light: In light mode on #FFFFFF, links (#cb9a04) reach 2.57:1 of the 4.5:1 text needs and accent fills (#F2B705) reach 1.82:1 of the 3:1 controls need. The nearest passing accent is #b38704. The build keeps your colour.

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):

SwitchAllowed values
shellbordered, sheet, enterprise, minimal, floating, grid, focus
headercommand, pill, tabs, mega, simple, island, index, path
homeDeprecated. 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
navtree, pills, mono, chevrons, plain, dock, chapters, overlay, sections
tocprogress, pills, dots, rule, plain, float, ruler, ticks
groupscollapsible, 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
headerBackgroundsolid, 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:

navPresetNotes
treeWorkbench
pillsPaper
monoConsole
chevronsAtlasGroups fold with a chevron
plainPlain
chaptersGridEvery group but the current one starts folded
overlayMargin
sectionsOrbitOne 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:

SwitchIts region
shellThe page frame — layout grid, columns and surfaces, and where blocks sit in the column
headerThe 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
homeDeprecated and ignored with a warning — the home components follow the preset
navThe sidebar
tocThe 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):

SwitchAllowed values
calloutlabelcol, tag, strip, box, soft, float, cell, sidenote
stepsrail, cards, prompt, procedure, list, stack, cells, margin
codedark, light, inset, navy, plain, float, cell, bleed
cardsbordered, tile, outline, accent, plain, bento, cell, rows
tabsunderline, pill, mono, boxed, text, segment, cells
apispec, card, term, boxed, plain, split, grid, stacked
codeRadiussite, 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.

json
{
"theme": "orbit",
"appearance": {
"layout": { "headerBackground": "solid" },
"components": { "code": "light", "codeRadius": "small" }
}
}

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 block

Every 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:

text
appearance.layout.nav: "tre" is not a layout.nav value. Use one of: tree, pills, mono, chevrons, plain, dock, chapters, overlay, sections. Did you mean "tree"?
appearance.colour: Unknown appearance key "colour".
appearance.components.callouts: Unknown components switch "callouts". Did you mean "callout"?

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:

1.
the default preset
2.
the named preset from theme
3.
themeOverrides
4.
the legacy colors block

colors 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:

1.
the v2 preset — the one named in theme, the organization theme's preset, or Workbench
2.
the v1 theme named in theme, mapped onto v2 — gravv sets accent #077155, layout.header: "tabs" and components.code: "inset", and keeps Workbench's command home; default changes nothing
3.
v1 features 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 → toggle
4.
the organization theme's appearance
5.
the site's appearance

Then the tokens — the colours, fonts, sizes and corners v2 pages draw with — are set from that appearance and layered, lowest priority first:

1.
the resolved appearance
2.
the organization theme's themeOverrides
3.
the site's themeOverrides
4.
the legacy colors and fonts blocks

So 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)

Warning

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.

json
{
"fonts": { "heading": "Plus Jakarta Sans", "body": "Inter", "mono": "JetBrains Mono" }
}

codeTheme

Warning

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.

json
{
"topbarCta": { "label": "Get API keys", "url": "https://dashboard.example.com/keys" },
"topbarLinks": [
{ "label": "Sign in", "url": "https://dashboard.example.com" }
]
}
KeyDescription
topbarCtaThe 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
topbarLinksPlain-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.

Note

dashboardUrl has no effect. Use topbarLinks instead, which lets you name the link.

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:

json
{
"topbarLinks": [
{ "label": "Sign in", "url": "https://dashboard.example.com" },
{
"label": "Resources",
"links": [
{ "label": "Changelog", "url": "/changelog", "description": "Everything that shipped" },
{ "label": "Status", "url": "https://status.example.com" },
{ "label": "Community", "url": "https://community.example.com" }
]
}
]
}
KeyDescription
labelThe group name, shown in the bar with a chevron
linksThe 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.

Note

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.

json
{
"features": {
"playground": true,
"copyPageActions": { "guides": true, "api": false },
"sidebarMethodBadges": true,
"codeLanguageSelector": "dropdown",
"aiAssistant": true,
"endpointBarAction": "tryIt",
"codeLineNumbers": false,
"panelLabels": "inline",
"copyControlStyle": "icon"
}
}
FlagDefaultDescription
playgroundtrueThe "Try it" request playground on API reference pages
copyPageActionstrueThe "Copy page" control and its open-in-AI menu. Accepts true/false for both surfaces, or { "guides": true, "api": false } to differ
sidebarMethodBadgestrueHTTP 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
codeLanguageTabstrueDeprecated, no-op — delete it. Never controlled anything — the panel only ever had a dropdown. Use codeLanguageSelector. stx migrate removes it
aiAssistanttrueAssistant 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)
codeLineNumbersfalseA 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
themeToggletrueDeprecated — 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
apiSectionLabelfalseShow 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.

Note
Style flags move into appearance on v2

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:

json
{ "features": { "copyPageActions": { "guides": true, "api": false } } }

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

Warning
Not applied by hosted builds

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.

json
{
"customCSS": "/custom.css"
}

scripts

Warning
Not applied by hosted builds

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.

json
{
"scripts": [
{ "src": "https://analytics.example.com/script.js", "async": true },
{ "src": "/custom.js", "defer": true }
]
}

Site Features

Top announcement bar, rendered above the header so it scrolls away with the page rather than taking height from the sticky header.

KeyTypeDefaultDescription
textstring—The announcement. Required; without it no bar is rendered
linkstring—Optional href — the whole announcement becomes the link
dismissiblebooleanfalseShow 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.

json
{
"banner": {
"text": "🚀 Version 2.0 is now available!",
"link": "/changelog/v2",
"dismissible": true
}
}

Search configuration.

json
{
"search": {
"enabled": true,
"placeholder": "Search docs..."
}
}
KeyTypeDefaultDescription
enabledbooleantruefalse turns site search off for readers, on doc engine v1 and v2 sites. See Turning search off
placeholderstring"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

json
{
"search": { "enabled": false }
}

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:

•
The header has no search button or box — on desktop, tablet and phone — and the navigation drawer has no search row.
•
A <SearchBar> in a page renders nothing.
•
⌘K / Ctrl+K (and / on doc engine v2) do nothing on the page; the browser keeps its own shortcut.
•
The 404 page has no search field and no Did you mean lookup. The missing path and Ask instead stay.
•
The assistant panel hides its Search for… and Search instead buttons.
•
Home search boxes ask instead of searching when the assistant is on — no Search / Ask switch, and Paper's Search button reads Ask. With the assistant off, or for a mode="search" box, they're left out. A suggestion chip without a link asks the assistant.
•
Pages make no search requests.

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.

json
{
"status": {
"label": "All systems operational",
"url": "https://status.example.com"
}
}
KeyTypeDescription
labelstringThe text beside the dot. Required — without it nothing renders, url or not
urlstringOptional 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.

Note

The label is static text. Syntext does not poll your status page — update the label and rebuild if the wording needs to change.

ai

Warning

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:

•
To turn the assistant on or off, use the aiAssistant feature flag.
•
To change the composer's placeholder, use search.placeholder.
json
{
"features": { "aiAssistant": true },
"search": { "placeholder": "Ask a question..." }
}

Redirects

redirects

URL redirect rules.

json
{
"redirects": [
{ "from": "/old-path", "to": "/new-path" },
{ "from": "/moved", "to": "/new-home", "status": 302 },
{ "from": "/docs/*", "to": "/:splat" }
]
}

Each entry takes:

FieldTypeDescription
fromstringPath to redirect from. Normalized to a leading slash, no trailing slash
tostringTarget — a site path or an absolute https:// URL
statusnumberHTTP 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.

Warning

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:

json
[
{ "from": "/old-path", "to": "/new-path" },
{ "source": "/legacy/quickstart", "destination": "/getting-started" }
]

This is handy when migrating from a platform that exports redirects as a file — stx migrate writes one automatically.

Merge behavior:

•
Entries from syntext.json and _redirects.json are combined into one list
•
On conflicting from paths, the syntext.json entry wins
•
If _redirects.json is not valid JSON (or not a JSON array), the build logs a warning and ignores the file — the build still succeeds
•
Entries missing from or to are silently dropped

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.

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.

json
{
"footer": {
"columns": [
{
"title": "Product",
"links": [
{ "label": "Documentation", "url": "/guides/quickstart" },
{ "label": "API Reference", "url": "/api-reference/overview" }
]
},
{
"title": "Legal",
"links": [
{ "label": "Privacy Policy", "url": "https://example.com/privacy" },
{ "label": "Terms of Service", "url": "https://example.com/terms" }
]
}
]
}
}

Each column takes:

FieldTypeDescription
titlestringColumn heading (optional)
linksarrayLinks in the column — each needs a label and a url

Behavior:

•
Full-bleed — the footer spans the entire viewport width, outside the content grid, on both guide and API reference pages
•
Relative URLs (/guides/...) navigate within your doc site; absolute URLs (https://...) open in a new tab
•
The brand column shows your logo (light/dark aware), project name, and social icons automatically
•
Columns with no valid links are skipped; omit footer entirely to keep the compact default footer

Deprecated 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.

DeprecatedUse insteadv2 only
languagelocale
ogImage (top level)seo.ogImage
redirects[].sourceredirects[].from
redirects[].destinationredirects[].to
i18n.sourceLocale, i18n.localei18n.defaultLocale
i18n.targetLocalesi18n.locales
syntext.config.json (the file)syntext.json
colors.accentthemeOverrides.colors.light.accent-strong and .dark.accent-strong
colors.backgroundthemeOverrides.colors.light.bg-page and .dark.bg-page
colors.primaryappearance.accentYes
fonts.heading, fonts.displayappearance.fonts.headingYes
fonts.bodyappearance.fonts.bodyYes
fonts.monoappearance.fonts.monoYes
features.navStyleappearance.layout.header (split → tabs, single → simple)Yes
features.sidebarStyleappearance.layout.nav (collapsible → chevrons, flat → plain)Yes
features.codeBlockStyleappearance.components.code (pill → dark, panel → inset)Yes
features.shellWidthappearance.widthYes
features.themeToggleappearance.toggleYes
appearance.layout.nav: "collapsible"appearance.layout.nav: "chevrons"
appearance.layout.homeNothing — delete it. Since 16 November 2026 it's ignored with a warning, never a build failure, and the home blocks follow the presetYes
features.codeLanguageTabsNothing — delete it (use features.codeLanguageSelector)
features.parameterStyleNothing — 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

KeyDescription
projectIdThe project this folder deploys to. Written by stx init --create and stx connect; read by the CLI only
baseUrlBase URL for the doc site's MCP tool manifest. Falls back to the MCP server integration's setting
customJSAccepted but not applied by hosted builds — see customCSS

Complete Example

json
{
"$schema": "https://syntext.dev/schema/syntext.json",
"name": "Acme API",
"description": "Complete API documentation for Acme Platform",
"theme": "workbench",
"appearance": { "accent": "#6366F1" },
"logo": {
"light": "/logo-light.svg",
"dark": "/logo-dark.svg"
},
"favicon": "/favicon.ico",
"features": {
"playground": true,
"endpointBarAction": "tryIt"
},
"github": "https://github.com/acme/api",
"socialLinks": [
{ "platform": "GitHub", "url": "https://github.com/acme" },
{ "platform": "X", "url": "https://x.com/acme" }
],
"tabs": [
{ "name": "Guides", "url": "/guides", "icon": "book" },
{ "name": "API Reference", "url": "/api-reference", "icon": "api" }
],
"navigation": [
{
"group": "Getting Started",
"pages": ["index", "quickstart", "authentication"]
},
{
"group": "Guides",
"pages": ["guides/webhooks", "guides/pagination", "guides/errors"]
}
],
"openapi": "./openapi.json",
"baseUrls": [
{ "url": "https://api.acme.com", "description": "Production" },
{ "url": "https://sandbox.acme.com", "description": "Sandbox" }
],
"footer": {
"columns": [
{
"title": "Product",
"links": [
{ "label": "Documentation", "url": "/guides/quickstart" },
{ "label": "Pricing", "url": "https://acme.com/pricing" }
]
},
{
"title": "Company",
"links": [
{ "label": "About", "url": "https://acme.com/about" },
{ "label": "Blog", "url": "https://acme.com/blog" }
]
}
]
}
}
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext