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

Deprecated syntax

The deprecation policy for syntext.json keys, frontmatter keys, MDX tags and props — and every deprecated form with its replacement.

8 min read

Doc engine v2 settled one name for each concept. The older names keep working for a while, and Syntext tells you about every one you use — with the file, the line and the exact replacement — before anything stops working.

Policy

1.

A deprecated form keeps working. The build log warns with the file, the line and the replacement:

text
docs/guide.mdx:12: <Caution> is deprecated. Use <Warning> instead.
2.

You get notice. When Syntext schedules a form's removal, members of workspaces with a live site are emailed — owners, admins and members alike. A live site is one with a production deploy that has more than the starter pages. Every member of a workspace whose live site's last production build used the form is notified; a v2-only form counts only on a site that already renders with doc engine v2. For the doc engine v2 changes, the notice can also go to every member of every workspace with a live site, whether or not the site uses a deprecated form. Where the build recorded usage, the email lists each form, how many places use it, the replacement and the date it stops working; otherwise it explains what changes in doc engine v2 in general terms. Each person gets one email, listing every affected project across all their workspaces. Notices are service email, so they arrive even if you've turned product email off. A project whose build used the form also shows a banner in the dashboard naming the file and the date it stops working, with a Fix automatically button and the stx migrate command. The emails and the build log point to both: run stx migrate, or use Fix automatically in your dashboard. The build warning gains the date:

text
docs/guide.mdx:12: <Caution> is deprecated and stops working on 2026-12-01. Use <Warning> instead.
3.

14 days later the build fails — never a silent change in output. The error lists every use with the exact fix:

text
1 deprecated form is no longer supported:
docs/guide.mdx:12: <Caution> is no longer supported (removed 2026-12-01). Fix: use <Warning>. Rename <Caution> to <Warning>; they always rendered the same. `stx migrate` rewrites it.
4.
Exception — v2-only moves. A few keys move a value into appearance, which only the doc engine v2 renderer reads (they're marked v2 only below). Adding appearance switches a site to v2, so on a site that still renders with v1 these stay warnings after the removal date; failing would force a renderer switch, not a rename. They follow the normal policy once the site is on v2.
5.

Unknown keys in syntext.json and frontmatter follow the same policy (config.unknown-key, frontmatter.unknown-key). Today they're warnings with a "did you mean":

text
syntext.json:3: Unknown key "nmae" is ignored. Did you mean "name"?
6.
Exception — the generated home. frontmatter.home, frontmatter.implicit-home and config.layout-home never fail a build. The generated home ended on doc engine v2 on 16 November 2026: every index page shows its own content in the frame its layout picks, home frontmatter and appearance.layout.home are ignored, each with a warning, and an index with no content of its own warns that it's empty. See Since 16 November 2026.

Until a removal date is announced for a form, it stays a warning.

Fixing them

There are three ways to rewrite deprecated syntax. All three apply the same rewrites — config keys, frontmatter keys, MDX tags and props, the config file name and, on a doc engine v2 site, the generated home — and none of them publishes anything on its own.

WayWhoWhat it saves
Fix automatically in the dashboardAny workspace memberA pull request (GitHub) or an unpublished draft (written in Syntext)
Your AI assistant, through the connector's fix_deprecated_syntaxAny workspace member with docs:writeA draft or a pull request, or more commits on a change you name
stx migrateAnyone with the filesThe files in place, for you to review and commit

Fix automatically in the dashboard

1.
On the deprecation banner (project overview or Settings › Appearance), click Fix automatically.
2.
The dialog shows a dry run: the files that change, each rewrite as before → after with its file and line, a diff per file, and what won't be changed and why. Nothing is written yet.
3.
Click Create pull request (a GitHub project) or Save as draft (a project written in Syntext). A link to the pull request or the draft follows — merge or publish it to put the fix live.

Convert home to content stays on the banner for converting only the generated home.

Through your AI assistant

Ask your assistant to fix deprecated syntax in a project. With the hosted connector, it calls fix_deprecated_syntax: a dry run first, then a draft (or a pull request on GitHub) when you ask it to save. Publish it with publish_changes, or review it in the dashboard first.

With the CLI

bash
stx check # list every deprecated form, with file and line
stx migrate --dry-run # show the rewrite as a diff
stx migrate # rewrite them in place
stx migrate --v2 # also apply the v2-only moves into appearance

stx migrate keeps your JSON formatting and YAML comments, never touches code fences or inline code, and is safe to run twice. It's the only way for a project published with stx deploy, whose files aren't stored in Syntext. The web editor shows the same warnings inline as you type.

Moving to doc engine v2

The v2-only moves — colors.primary, fonts.* and the features style flags — put values into appearance, which switches a v1 site to doc engine v2 and changes how it looks. Every way leaves them out unless you ask:

WayOpt in
DashboardTick Also move to doc engine v2 (changes the site's look) — unchecked by default
Connectorv2: true
CLIstx migrate --v2
API"v2": true

On a site that already renders with doc engine v2 they're applied without asking, and the generated docs home is converted to home components from your last build's data. A site with no build yet keeps its home, with the reason.

The API does the same for your own tools.

Where you see them

WhereWhat it shows
Build logA warning per use, with file and line; an error after the removal date
stx checkThe same messages, locally. --strict fails on them; --json includes each code
Web editorInline diagnostics on pages and on syntext.json / syntext.yml
DashboardA banner on the project overview and Settings › Appearance: the file and line, the replacement, the date it stops working, a link to open the file, Fix automatically, and stx migrate
APIGET /v1/projects/{projectId}/deprecations — what the last production build used, with dates
EmailOne notice per person, listing all their affected projects, when a removal date is set. It goes to every member of each workspace with a live site that uses the form; the doc engine v2 notice can go to every member of every workspace with a live site, with per-form detail where the last production build recorded usage

The full table is published as JSON at https://api.syntext.dev/v1/schema/deprecations.json — it's what stx migrate reads.

Every deprecated form

38 codes. The code appears in stx check --json, the editor and the API.

syntext.json

CodeDeprecatedUse insteadv2 only
config.colors-primarycolors.primaryappearance.accentYes
config.colors-accentcolors.accentthemeOverrides.colors.light.accent-strong and themeOverrides.colors.dark.accent-strong
config.colors-backgroundcolors.backgroundthemeOverrides.colors.light.bg-page and themeOverrides.colors.dark.bg-page
config.fonts-headingfonts.headingappearance.fonts.headingYes
config.fonts-displayfonts.displayappearance.fonts.headingYes
config.fonts-bodyfonts.bodyappearance.fonts.bodyYes
config.fonts-monofonts.monoappearance.fonts.monoYes
config.features-navStylefeatures.navStyleappearance.layout.header (split → tabs, single → simple)Yes
config.features-sidebarStylefeatures.sidebarStyleappearance.layout.nav (collapsible → chevrons, flat → plain)Yes
config.features-codeBlockStylefeatures.codeBlockStyleappearance.components.code (pill → dark, panel → inset)Yes
config.features-shellWidthfeatures.shellWidthappearance.width (same values)Yes
config.features-themeTogglefeatures.themeToggleappearance.toggleYes
config.layout-nav-collapsibleappearance.layout.nav: "collapsible"appearance.layout.nav: "chevrons"
config.layout-homeappearance.layout.home — in syntext.json, project settings or an organization themeNothing — delete it. Since 16 November 2026 it's ignored with a warning and the home blocks follow the presetYes
config.features-codeLanguageTabsfeatures.codeLanguageTabsNothing — delete it (it never did anything; use features.codeLanguageSelector)
config.features-parameterStylefeatures.parameterStyleNothing — delete it (it never did anything)
config.languagelanguagelocale
config.og-imageogImage (top level)seo.ogImage
config.redirect-sourceredirects[].sourceredirects[].from
config.redirect-destinationredirects[].destinationredirects[].to
config.i18n-source-localei18n.sourceLocalei18n.defaultLocale
config.i18n-localei18n.localei18n.defaultLocale
config.i18n-target-localesi18n.targetLocalesi18n.locales
config.file-nameThe file syntext.config.jsonsyntext.json
config.unknown-keyA key syntext.json doesn't defineThe closest valid key, or nothing — rename or delete it by hand

When a move's target is already set, stx migrate keeps the target and removes the old key.

Frontmatter

CodeDeprecatedUse instead
frontmatter.noIndexnoIndexnoindex
frontmatter.fullWidthfullWidth: truelayout: full-width (fullWidth: false is deleted)
frontmatter.homehome on the index page (the generated home)The home components in index.mdx. Ignored with a warning since 16 November 2026; v2 only
frontmatter.implicit-homeA v2 index page that relied on the generated home: no home, and no home components in its bodyThe home components in index.mdx. Since 16 November 2026 the page shows only its own content
frontmatter.unknown-keyA frontmatter key Syntext doesn't readThe closest valid key, or nothing — rename or delete it by hand

home: false isn't deprecated — it's harmless to keep. The dashboard's Appearance › Convert home to content and Fix automatically, fix_deprecated_syntax and stx migrate (stx 0.9.0 and later) convert the home for you, or convert by hand — see Moving off the generated home.

MDX tags and props

CodeDeprecatedUse instead
mdx.caution<Caution><Warning>
mdx.callout-type<Callout type="…">The named callout: note → <Note>, info → <Info>, tip → <Tip>, warning and caution → <Warning>, danger → <Danger>. Other values are left for you to fix
mdx.update-label<Update label="…"><Update title="…">
mdx.endpoint-url<Endpoint url="…"><Endpoint path="…">
mdx.searchbar-hint<SearchBar hint="…"><SearchBar kbd="…">. Both engines still read hint (hint="false" hides the shortcut hint); kbd wins when both are set
mdx.playground-base-url<Playground base-url="…"><Playground baseUrl="…">
mdx.playground-auth-label<Playground auth-label="…"><Playground authLabel="…">
mdx.playground-key-label<Playground key-label="…"><Playground keyLabel="…">

The new names render exactly as the old ones did, so switching changes nothing on the page.

Kept as they are

These pairs look like duplicates but aren't, so they were deliberately not renamed:

•
hideRightSidebar and toc: false — on API prose pages hideRightSidebar also drops the example column, which toc doesn't.
•
category and section — category also sets the search category.
•
<APIEndpoint> and <Endpoint> — they render differently per page type.
•
draft, hidden, sidebarPosition, toc, sidebar, feedback, editUrl — already one name per concept.
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext