Migrate from Mintlify
Move your docs from Mintlify to Syntext — most content works unchanged.
Syntext uses MDX with a very similar component set to Mintlify, so most content migrates with minimal changes. A typical migration takes under an hour.
Automatic Migration
The CLI can convert a Mintlify project automatically:
This copies your pages into docs/, writes a starter syntext.json from mint.json and a _redirects.json. It is a first pass, not a finished site:
<Card> becomes a ## heading, <Tabs>/<Tab> become MDX comments, <Accordion> becomes <details>, <ParamField>/<ResponseField> become list items. If you'd rather keep them (they render the same in Syntext — see the table below), copy your original pages over instead and run only stx check.<Frame>, <CodeGroup>, <Snippet>, <RequestExample> and <ResponseExample> and leaves them as they are.syntext.json it writes isn't in the current format — replace it as in step 2 below. Only mint.json is read; a newer docs.json isn't.See stx migrate --from for the details.
What Maps Directly
| Mintlify | Syntext | Notes |
|---|---|---|
.mdx pages | .mdx pages | Unchanged |
mint.json | syntext.json | Same concepts, different key names |
<Note>, <Warning>, <Tip>, <Info> | Same | Callouts |
<CodeGroup> | Same | Code Blocks |
<Card>, <CardGroup> | Same | Cards |
<Tabs>, <Tab> | Same | Tabs |
<Steps>, <Step> | Same | Steps |
<ParamField>, <ResponseField> | <ParamField> | API Components |
<Accordion> | <Accordion> | Same |
| OpenAPI page generation | OpenAPI import | Point Syntext at your spec |
Frontmatter title / description | Same behavior | Rendered as the page H1 + lead paragraph when the body has no H1 — see below |
redirects in mint.json | redirects in syntext.json or a _redirects.json file | See the migration steps below |
Frontmatter title and description
Like Mintlify, Syntext renders the frontmatter title as the visible page heading — but only when the page body contains no # Heading of its own. When the body has no H1, the build synthesizes one from title and renders description as a lead paragraph below it. When the body already has an H1, nothing is synthesized and the frontmatter values are used for metadata only.
Use one style per page: either rely on the frontmatter title (Mintlify style) or write an explicit # Heading in the body — not both. Content migrated from Mintlify works unchanged, since Mintlify pages don't repeat the title in the body. Details in the frontmatter reference.
Migration Steps
- 01Step 1 of 61 ›Step 11.Initialize Syntext in your docs repo
In a new, empty folder:
bashstx init my-docs --preset workbenchThis creates a
syntext.jsonand starter pages. Copy your Mintlify pages intodocs/—stx initwritesdocs/index.mdx, so keep the one you want. - 02Step 2 of 62 ›Step 22.Convert mint.json to syntext.json
The navigation structure maps nearly 1:1:
mint.json (before)syntext.json (after){"name": "Acme","colors": { "primary": "#6366F1" },"navigation": [{"group": "Getting Started","pages": ["introduction", "quickstart"]}],"tabs": [{ "name": "API Reference", "url": "api-reference" }]}{"name": "Acme","theme": "workbench","appearance": { "accent": "#6366F1" },"navigation": [{"group": "Getting Started","pages": ["introduction", "quickstart"]}],"tabs": [{ "name": "API Reference", "url": "/api-reference/overview", "icon": "code" }]}Key differences:
••tabs[].urlis a full path to the tab's landing page, not a folder prefix•topbarLinks→topbarLinks(same shape:[{ label, url }])•topbarCtaButton→topbarCta({ label, url })•anchors→ usetabsinsteadSee the syntext.json reference for every field.
- 03Step 3 of 63 ›Step 33.Verify components renderbashstx dev
Open the preview URL
stx devprints and click through your pages. Each save rebuilds the preview; build errors show in the terminal. Runstx checkfor deprecated syntax, unknown keys and broken links.Components to double-check:
•<Frame>→ use a plain Markdown image•<Snippet>→ use standard MDX imports; to show code from your repository, use{@embed symbolName}•Mintlify-specific props (e.g.iconType) are ignored harmlessly - 04Step 4 of 64 ›Step 44.Bring your redirects
If your
mint.jsonhas aredirectsarray, you have two equivalent options:1.Copy it intosyntext.jsonunder the sameredirectskey2.Ship it as a standalone_redirects.jsonfile at your docs root or repo root — the build loads and merges it automaticallyjson[{ "from": "/old-path", "to": "/new-path" },{ "source": "/legacy/quickstart", "destination": "/getting-started" }]Both
{ "from", "to" }and Mintlify-style{ "source", "destination" }keys are accepted.stx migratealready writes a_redirects.jsonwith entries for every page whose slug changed during conversion — keep that file in your repo and it just works. If bothsyntext.jsonand_redirects.jsondefine the same path, thesyntext.jsonentry wins. See the redirects reference for the full behavior. - 05Step 5 of 65 ›Step 55.Import your OpenAPI spec (if applicable)
If Mintlify generated API pages from an OpenAPI spec, list the same spec under
openapiinsyntext.json— endpoint pages and Try it are generated at every build:json{"openapi": "./openapi.json"}Keep the spec file in your docs folder so
stx deployuploads it. See OpenAPI sync. - 06Step 6 of 66 ›Step 66.Deploybashstx deploy
Your site is live at
{slug}-docs.syntext.dev. Then point your custom domain at Syntext and update DNS.
What You Gain
Stuck on a component or config field that doesn't map? Ask in Discord — migrations are a priority support topic.