Migrate from Mintlify

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:

cd your-mintlify-docs
stx migrate --from mintlify --dry-run   # preview what will change
stx migrate --from mintlify             # convert content + config

This converts mint.json to syntext.json and rewrites unsupported components. Review the output, then follow the manual steps below for anything flagged.

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	Frontmatter

Migration Steps

stx init

This creates a syntext.json and detects your existing docs/ content.

The navigation structure maps nearly 1:1:

{
"name": "Acme",
"colors": { "primary": "#6366F1" },
"navigation": [
{
"group": "Getting Started",
"pages": ["introduction", "quickstart"]
}
],
"tabs": [
{ "name": "API Reference", "url": "api-reference" }
]
}

{
"name": "Acme",
"colors": { "primary": "#6366F1" },
"navigation": [
{
"group": "Getting Started",
"pages": ["introduction", "quickstart"]
}
],
"tabs": [
{ "name": "API Reference", "url": "/api-reference/overview", "icon": "api" }
]
}

Key differences:

tabs[].url is a full path to the tab's landing page, not a folder prefix
topbarLinks / topbarCtaButton → socialLinks and footer.columns
anchors → use tabs instead

See the syntext.json reference for every field.

stx dev

Open http://localhost:3333 and click through your pages. The dev server hot-reloads and reports MDX compile errors inline.

Components to double-check:

<Frame> → use plain Markdown images or <Card img="...">
<Snippet> → use {@embed symbolName} or standard MDX imports
Mintlify-specific props (e.g. iconType) are ignored harmlessly

If Mintlify generated API pages from an OpenAPI spec, upload the same spec to Syntext — endpoint pages and the try-it playground are generated automatically:

curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
-H "Authorization: Bearer $STX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.acme.com/openapi.json" }'

stx deploy

Your site is live at {slug}-docs.syntext.dev. Then point your custom domain at Syntext and update DNS.

What You Gain

Code annotations — generate API reference from doc comments in your actual source, with drift detection
AI assistant trained on your docs, with gap detection
Analytics including content health and zero-result searches
Collaboration workflows — reviews, approval gates, scheduled publishing

Stuck on a component or config field that doesn't map? Ask in Discord — migrations are a priority support topic.