/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
CLI CLI Reference stx migrate

stx migrate

Rewrite deprecated Syntext syntax in place, or migrate documentation from Mintlify, Docusaurus, GitBook or ReadMe.

7 min read

stx migrate does two jobs:

•
Without --from — rewrites deprecated Syntext syntax in your project: config keys, frontmatter keys, MDX tags and props, and the config file name.
•
With --from <platform> — converts a project from another docs platform to Syntext.

Usage

bash
stx migrate [options] # rewrite deprecated Syntext syntax
stx migrate --from <platform> [options] # import from another platform

Options

FlagAliasTypeDefaultDescription
--dir <dir>-dstring.Project folder that holds syntext.json. With --from, the source docs folder
--dry-runbooleanfalseShow what would change without writing files — a unified diff for Syntext syntax
--jsonbooleanfalsePrint the result as JSON
--v2booleanfalseAlso apply rewrites that move values into appearance. This switches a v1 site to doc engine v2
--offlinebooleanfalseUse the deprecation table bundled with stx instead of fetching the published one
--from <platform>stringImport from another platform instead: mintlify, docusaurus, gitbook, readme
--output <dir>-ostringdocsOutput directory (with --from)

Rewrite deprecated syntax

Renamed keys, tags and props keep working for a while, then stop. stx migrate rewrites every one it finds, in place.

Which pages it reads

Pages are read where the hosted build reads them: from docs/ when it holds .md or .mdx pages at its top level, otherwise from the folder that holds syntext.json — so a site whose pages sit next to syntext.json is covered too (stx 0.11.1 and later). node_modules, dist, _syntext/ and dot folders are skipped. stx check reads the same pages.

Note

No terminal? Fix automatically in the dashboard and the connector's fix_deprecated_syntax apply the same rewrites and save them as a pull request or a draft. See Fixing them.

Preview first

bash
stx migrate --dry-run

Prints a unified diff of every change, then a summary. Nothing is written.

diff
--- a/docs/components/updates.mdx
+++ b/docs/components/updates.mdx
@@ -29,7 +29,7 @@
-<Update label="June 2026" description="Week of June 22">
+<Update title="June 2026" description="Week of June 22">
text
Would rewrite 3 deprecated forms in 2 files. Nothing was written (--dry-run).
Rules: the published deprecation table.
docs/components/updates.mdx:32 <Update label="…"> → <Update title="…">
...

Apply

bash
stx migrate
text
Rewrote 3 deprecated forms in 2 files.
Rules: the published deprecation table.
...
Run `stx check` to confirm, then review and commit the changes.

Running it again changes nothing — the rewrite is idempotent, and a clean project prints No deprecated syntax found.

What it rewrites

WhereWhat happens
syntext.jsonKeys are moved or renamed (language → locale, ogImage → seo.ogImage, redirects[].source → from, …). The rest of the file keeps its formatting
syntext.yml / syntext.yamlThe same rewrites. Comments are kept
syntext.config.jsonRenamed to syntext.json, unless a syntext.json already exists
FrontmatternoIndex → noindex, fullWidth: true → layout: full-width (fullWidth: false is deleted)
MDX<Caution> → <Warning>, <Callout type="tip"> → <Tip>, <Update label> → title, <Endpoint url> → path, <SearchBar hint> → kbd, <Playground> base-url / auth-label / key-label → baseUrl / authLabel / keyLabel

Tags and props are never rewritten inside code fences or inline code, so a page that shows the old syntax as an example keeps it. When a target is already set — say a page has both noIndex and noindex — the existing value wins and the old key is removed.

The full list, with every rule, is on Deprecated syntax.

The generated home

On a doc engine v2 site, stx migrate (0.9.0 and later) also moves the docs root index.mdx off the generated home, which ended on 16 November 2026. The page gets the home components your preset's home drew — <Hero title>, <SectionCards>, <LatestUpdates>, … — in the layout's order, with any authored home items as their children. home is dropped, layout: wide replaces any layout, and the old body stays below, so the page looks the way the generated home did.

The conversion needs your site's data (home layout, changelog, API and CLI sections). Logged in, with a projectId in syntext.json, stx asks the last build for it, without writing anything. Otherwise — not logged in, no project, no build yet, the API unreachable, or --offline — it works it out from syntext.json and your page paths, and the summary says which it used and why. With --json it's reported as home: { file, from: "last-build" | "local", reason? }.

See Moving off the generated home.

What it holds back

Some forms are listed under Not rewritten in the summary instead of being changed:

•
Moves into appearance — colors.primary, fonts.* and the features style flags (navStyle, sidebarStyle, codeBlockStyle, shellWidth, themeToggle). Adding appearance switches a v1 site to the doc engine v2 renderer, so these wait until you pass --v2. On a site that's already on v2 they're applied without it.
•
Anything that needs a person — a prop set under both its old and new name, a <Callout type> value Syntext doesn't know, or a syntext.config.json next to an existing syntext.json. Each line says what to do by hand.

Unknown keys are never rewritten automatically either; stx check names the closest valid key.

Anything still left over is listed under Still reported by stx check.

Where the rules come from

The rules are fetched from https://api.syntext.dev/v1/schema/deprecations.json, so an older stx still applies newly published rewrites. If the table can't be fetched — or with --offline — stx uses the copy bundled with it, and the summary says so. A rule type the installed stx doesn't understand is reported with Update stx and run it again.

JSON output

bash
stx migrate --dry-run --json

Prints one object with success, table (source: remote or bundled), and the applied, held and remaining items with each file's diff.

Import from another platform

Copy an existing documentation project's pages into docs/, with a first pass over each platform's own syntax, a starter syntext.json and a redirect map. Expect to finish the conversion by hand — see What gets converted.

Migrate from Mintlify

bash
stx migrate --from mintlify
text
✔ Migration complete from mintlify
Pages converted: 47
Config generated: Yes
Redirects: 12
Redirect map saved to: docs/_redirects.json

Preview first (dry run)

bash
stx migrate --from docusaurus --dry-run

Reports the pages, config, and redirects that would be produced — without touching the filesystem.

Custom source and output directories

bash
stx migrate --from gitbook --dir ./old-docs --output ./docs

What gets converted

Pages are written to --output (default docs), and the config to syntext.json in the folder above it.

PlatformPagesConfig
Mintlify<Card> becomes a ## heading and <CardGroup> is dropped; <Accordion> becomes <details>; <Tabs>/<Tab> become MDX comments; <ParamField>/<ResponseField> become list items. <Frame>, <CodeGroup>, <Snippet>, <RequestExample> and <ResponseExample> are left as they are, with a warningRead from mint.json only (docs.json isn't read): the name and navigation groups
Docusaurus:::note admonitions become blockquotes (> NOTE: …); @theme and @docusaurus imports are removed; <Tabs>/<TabItem> become MDX commentsThe site title from docusaurus.config.js. Navigation isn't converted — sidebars.js is only checked
GitBook.md becomes .mdx with a title added; {% hint %} becomes a blockquote; tabs become MDX comments; {% embed %} and {% file %} become linksNavigation groups from SUMMARY.md
ReadMeNumeric filename prefixes are removed (01-intro.md → intro.mdx)A name only

Redirects for pages whose URL changed are saved to <output>/_redirects.json. Move that file next to syntext.json, or copy the entries into redirects.

Warning

The generated syntext.json isn't in Syntext's current format yet: its navigation entries use title/items instead of group/pages, and theme is an object. Before you build, rewrite navigation as groups of pages, and replace theme with a preset and appearance.accent. stx check reports what's left. Components that were flattened (cards, tabs, accordions) have direct Syntext equivalents — Cards, Tabs, Accordions — that you can put back.

Warnings are printed for anything that needs manual attention.

After migrating

bash
stx migrate # rewrite any deprecated Syntext syntax the import produced
stx check # validate the converted content
stx dev # deploy a preview
stx deploy # publish
•
Deprecated syntax — every deprecated form and the policy
•
stx check — find deprecated syntax and validate after migration
•
Migrate from Mintlify — step-by-step guide
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext