/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Migrations Migrate from Mintlify

Migrate from Mintlify

Move your docs from Mintlify to Syntext — most content works unchanged.

5 min read

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:

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

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:

•
It flattens some components Syntext supports natively — <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.
•
It warns on <Frame>, <CodeGroup>, <Snippet>, <RequestExample> and <ResponseExample> and leaves them as they are.
•
The 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

MintlifySyntextNotes
.mdx pages.mdx pagesUnchanged
mint.jsonsyntext.jsonSame concepts, different key names
<Note>, <Warning>, <Tip>, <Info>SameCallouts
<CodeGroup>SameCode Blocks
<Card>, <CardGroup>SameCards
<Tabs>, <Tab>SameTabs
<Steps>, <Step>SameSteps
<ParamField>, <ResponseField><ParamField>API Components
<Accordion><Accordion>Same
OpenAPI page generationOpenAPI importPoint Syntext at your spec
Frontmatter title / descriptionSame behaviorRendered as the page H1 + lead paragraph when the body has no H1 — see below
redirects in mint.jsonredirects in syntext.json or a _redirects.json fileSee 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.

Note

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

  1. 01Step 1 of 61 ›Step 11.
    Initialize Syntext in your docs repo

    In a new, empty folder:

    bash
    stx init my-docs --preset workbench

    This creates a syntext.json and starter pages. Copy your Mintlify pages into docs/ — stx init writes docs/index.mdx, so keep the one you want.

  2. 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" }
    ]
    }

    Key differences:

    •
    colors.primary → a preset as theme, with appearance.accent for your brand colour
    •
    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.

  3. 03Step 3 of 63 ›Step 33.
    Verify components render
    bash
    stx dev

    Open the preview URL stx dev prints and click through your pages. Each save rebuilds the preview; build errors show in the terminal. Run stx check for 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
  4. 04Step 4 of 64 ›Step 44.
    Bring your redirects

    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
    json
    [
    { "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.

  5. 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 openapi in syntext.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 deploy uploads it. See OpenAPI sync.

  6. 06Step 6 of 66 ›Step 66.
    Deploy
    bash
    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 that answers from your docs, with gap detection
•
Insights including content health and zero-result searches
•
Workflow — reviews, approval gates, scheduled publishing
Note

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

Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext