---
title: Migrate from Mintlify
description: "Move your docs from Mintlify to Syntext — most content works unchanged."
---

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

```bash
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](/components/callouts) |
| `<CodeGroup>` | Same | [Code Blocks](/components/code-blocks) |
| `<Card>`, `<CardGroup>` | Same | [Cards](/components/cards) |
| `<Tabs>`, `<Tab>` | Same | [Tabs](/components/tabs) |
| `<Steps>`, `<Step>` | Same | [Steps](/components/steps) |
| `<ParamField>`, `<ResponseField>` | `<ParamField>` | [API Components](/components/api-components) |
| `<Accordion>` | `<Accordion>` | Same |
| OpenAPI page generation | OpenAPI import | Point Syntext at your spec |
| Frontmatter `title` / `description` | Same | [Frontmatter](/configuration/frontmatter) |

## Migration Steps

<Steps>
<Step title="Initialize Syntext in your docs repo">
```bash
stx init
```
This creates a `syntext.json` and detects your existing `docs/` content.
</Step>

<Step title="Convert mint.json to syntext.json">
The navigation structure maps nearly 1:1:

<CodeGroup>
```json mint.json (before)
{
  "name": "Acme",
  "colors": { "primary": "#6366F1" },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    }
  ],
  "tabs": [
    { "name": "API Reference", "url": "api-reference" }
  ]
}
```

```json syntext.json (after)
{
  "name": "Acme",
  "colors": { "primary": "#6366F1" },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    }
  ],
  "tabs": [
    { "name": "API Reference", "url": "/api-reference/overview", "icon": "api" }
  ]
}
```
</CodeGroup>

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](/configuration/syntext-json) for every field.
</Step>

<Step title="Verify components render">
```bash
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
</Step>

<Step title="Import your OpenAPI spec (if applicable)">
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:

```bash
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" }'
```
</Step>

<Step title="Deploy">
```bash
stx deploy
```
Your site is live at `{slug}-docs.syntext.dev`. Then point your [custom domain](/guides/custom-domains) at Syntext and update DNS.
</Step>
</Steps>

## What You Gain

- **Code annotations** — generate API reference from doc comments in your actual source, with [drift detection](/concepts/annotations)
- **AI assistant** trained on your docs, with gap detection
- **[Analytics](/platform/analytics)** including content health and zero-result searches
- **[Collaboration workflows](/platform/collaboration)** — reviews, approval gates, scheduled publishing

<Note>
Stuck on a component or config field that doesn't map? Ask in [Discord](https://discord.gg/syntext) — migrations are a priority support topic.
</Note>