stx migrate
Rewrite deprecated Syntext syntax in place, or migrate documentation from Mintlify, Docusaurus, GitBook or ReadMe.
stx migrate does two jobs:
--from — rewrites deprecated Syntext syntax
in your project: config keys, frontmatter keys, MDX tags and props, and the
config file name.--from <platform> — converts a project from another docs platform
to Syntext.Usage
Options
| Flag | Alias | Type | Default | Description |
|---|---|---|---|---|
--dir <dir> | -d | string | . | Project folder that holds syntext.json. With --from, the source docs folder |
--dry-run | boolean | false | Show what would change without writing files — a unified diff for Syntext syntax | |
--json | boolean | false | Print the result as JSON | |
--v2 | boolean | false | Also apply rewrites that move values into appearance. This switches a v1 site to doc engine v2 | |
--offline | boolean | false | Use the deprecation table bundled with stx instead of fetching the published one | |
--from <platform> | string | Import from another platform instead: mintlify, docusaurus, gitbook, readme | ||
--output <dir> | -o | string | docs | Output 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.
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
Prints a unified diff of every change, then a summary. Nothing is written.
Apply
Running it again changes nothing — the rewrite is idempotent, and a clean
project prints No deprecated syntax found.
What it rewrites
| Where | What happens |
|---|---|
syntext.json | Keys are moved or renamed (language → locale, ogImage → seo.ogImage, redirects[].source → from, …). The rest of the file keeps its formatting |
syntext.yml / syntext.yaml | The same rewrites. Comments are kept |
syntext.config.json | Renamed to syntext.json, unless a syntext.json already exists |
| Frontmatter | noIndex → 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:
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.<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
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
Preview first (dry run)
Reports the pages, config, and redirects that would be produced — without touching the filesystem.
Custom source and output directories
What gets converted
Pages are written to --output (default docs), and the config to
syntext.json in the folder above it.
| Platform | Pages | Config |
|---|---|---|
| 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 warning | Read 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 comments | The 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 links | Navigation groups from SUMMARY.md |
| ReadMe | Numeric 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.
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.