Deprecated syntax
The deprecation policy for syntext.json keys, frontmatter keys, MDX tags and props — and every deprecated form with its replacement.
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
A deprecated form keeps working. The build log warns with the file, the line and the replacement:
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:
14 days later the build fails — never a silent change in output. The error lists every use with the exact fix:
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.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":
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.
| Way | Who | What it saves |
|---|---|---|
| Fix automatically in the dashboard | Any workspace member | A pull request (GitHub) or an unpublished draft (written in Syntext) |
Your AI assistant, through the connector's fix_deprecated_syntax | Any workspace member with docs:write | A draft or a pull request, or more commits on a change you name |
stx migrate | Anyone with the files | The files in place, for you to review and commit |
Fix automatically in the dashboard
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
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:
| Way | Opt in |
|---|---|
| Dashboard | Tick Also move to doc engine v2 (changes the site's look) — unchecked by default |
| Connector | v2: true |
| CLI | stx 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
| Where | What it shows |
|---|---|
| Build log | A warning per use, with file and line; an error after the removal date |
stx check | The same messages, locally. --strict fails on them; --json includes each code |
| Web editor | Inline diagnostics on pages and on syntext.json / syntext.yml |
| Dashboard | A 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 |
| API | GET /v1/projects/{projectId}/deprecations — what the last production build used, with dates |
| One 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
| Code | Deprecated | Use instead | v2 only |
|---|---|---|---|
config.colors-primary | colors.primary | appearance.accent | Yes |
config.colors-accent | colors.accent | themeOverrides.colors.light.accent-strong and themeOverrides.colors.dark.accent-strong | |
config.colors-background | colors.background | themeOverrides.colors.light.bg-page and themeOverrides.colors.dark.bg-page | |
config.fonts-heading | fonts.heading | appearance.fonts.heading | Yes |
config.fonts-display | fonts.display | appearance.fonts.heading | Yes |
config.fonts-body | fonts.body | appearance.fonts.body | Yes |
config.fonts-mono | fonts.mono | appearance.fonts.mono | Yes |
config.features-navStyle | features.navStyle | appearance.layout.header (split → tabs, single → simple) | Yes |
config.features-sidebarStyle | features.sidebarStyle | appearance.layout.nav (collapsible → chevrons, flat → plain) | Yes |
config.features-codeBlockStyle | features.codeBlockStyle | appearance.components.code (pill → dark, panel → inset) | Yes |
config.features-shellWidth | features.shellWidth | appearance.width (same values) | Yes |
config.features-themeToggle | features.themeToggle | appearance.toggle | Yes |
config.layout-nav-collapsible | appearance.layout.nav: "collapsible" | appearance.layout.nav: "chevrons" | |
config.layout-home | appearance.layout.home — in syntext.json, project settings or an organization theme | Nothing — delete it. Since 16 November 2026 it's ignored with a warning and the home blocks follow the preset | Yes |
config.features-codeLanguageTabs | features.codeLanguageTabs | Nothing — delete it (it never did anything; use features.codeLanguageSelector) | |
config.features-parameterStyle | features.parameterStyle | Nothing — delete it (it never did anything) | |
config.language | language | locale | |
config.og-image | ogImage (top level) | seo.ogImage | |
config.redirect-source | redirects[].source | redirects[].from | |
config.redirect-destination | redirects[].destination | redirects[].to | |
config.i18n-source-locale | i18n.sourceLocale | i18n.defaultLocale | |
config.i18n-locale | i18n.locale | i18n.defaultLocale | |
config.i18n-target-locales | i18n.targetLocales | i18n.locales | |
config.file-name | The file syntext.config.json | syntext.json | |
config.unknown-key | A key syntext.json doesn't define | The 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
| Code | Deprecated | Use instead |
|---|---|---|
frontmatter.noIndex | noIndex | noindex |
frontmatter.fullWidth | fullWidth: true | layout: full-width (fullWidth: false is deleted) |
frontmatter.home | home 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-home | A v2 index page that relied on the generated home: no home, and no home components in its body | The home components in index.mdx. Since 16 November 2026 the page shows only its own content |
frontmatter.unknown-key | A frontmatter key Syntext doesn't read | The 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
| Code | Deprecated | Use 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.