Guides
View as Markdown Open in ChatGPT Open in Claude

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 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

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 → topbarLinks (same shape: [{ label, url }])
  • topbarCtaButton → topbarCta ({ label, url })
  • 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 your mint.json has a redirects array, you have two equivalent options:

  1. Copy it into syntext.json under the same redirects key
  2. Ship it as a standalone _redirects.json file at your docs root or repo root — the build loads and merges it automatically
[
{ "from": "/old-path", "to": "/new-path" },
{ "source": "/legacy/quickstart", "destination": "/getting-started" }
]

Both { "from", "to" } and Mintlify-style { "source", "destination" } keys are accepted. stx migrate already writes a _redirects.json with entries for every page whose slug changed during conversion — keep that file in your repo and it just works. If both syntext.json and _redirects.json define the same path, the syntext.json entry wins. See the redirects reference for the full behavior.

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.
Was this page helpful?