How to migrate from Mintlify to Scalar

Mintlify says that by default your documentation lives in a private, Mintlify-owned repository, and that you can move it to your own GitHub repository from the Git Settings dashboard. If you have not done that yet, do it first. Everything after this step works from a normal clone.

If your repository still has a mint.json, Mintlify's settings page describes it as deprecated in favour of docs.json and says mint dev upgrades it for you. Upgrading first is optional, but docs.json is the shape this guide maps from.

Keep the Mintlify site live until the Scalar one is ready. You will switch DNS at the very end.

Take a typical Mintlify navigation with a guides tab and an API reference tab:

{
  "name": "Acme",
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          { "group": "Get started", "pages": ["introduction", "quickstart"] },
          { "group": "Guides", "pages": ["guides/authentication", "guides/webhooks"] }
        ]
      },
      {
        "tab": "API Reference",
        "groups": [{ "group": "Endpoints", "openapi": "openapi.yaml" }]
      }
    ]
  }
}

The same structure in Scalar looks like this. Route keys are the URLs, and a group keyed / adds no prefix, so /quickstart stays /quickstart:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "info": {
    "title": "Acme"
  },
  "navigation": {
    "tabs": [
      { "title": "Guides", "to": "/" },
      { "title": "API Reference", "to": "/api-reference" }
    ],
    "routes": {
      "/": {
        "type": "group",
        "title": "Get started",
        "mode": "flat",
        "children": {
          "/": {
            "type": "page",
            "title": "Introduction",
            "filepath": "introduction.mdx"
          },
          "/quickstart": {
            "type": "page",
            "title": "Quickstart",
            "filepath": "quickstart.mdx"
          }
        }
      },
      "/guides": {
        "type": "group",
        "title": "Guides",
        "mode": "flat",
        "children": {
          "/authentication": {
            "type": "page",
            "title": "Authentication",
            "filepath": "guides/authentication.mdx"
          },
          "/webhooks": {
            "type": "page",
            "title": "Webhooks",
            "filepath": "guides/webhooks.mdx"
          }
        }
      },
      "/api-reference": {
        "type": "openapi",
        "title": "API Reference",
        "filepath": "openapi.yaml"
      }
    }
  },
  "siteConfig": {
    "subdomain": "acme",
    "logo": "https://example.com/logo.svg",
    "theme": "default"
  }
}

Three differences catch people out:

• Titles live in the config. In Scalar, the route's title is what the sidebar shows, whatever the page's frontmatter says. Frontmatter title and description still apply to the page itself.
• Extensions are required. "filepath" points at the real file, .mdx or .md.
• Groups can shape URLs. A group keyed /guides prefixes its children. If your Mintlify URLs did not have that prefix, key the group / instead, as the first group above does.

Validate the result with npx @scalar/cli project check-config. Navigation covers every route type and group mode.

This is the part to budget time for. Scalar Docs supports MDX, and several Mintlify names already work in Scalar's MDX as aliases: <Accordion> renders as a Detail, and <Columns> and <CardGroup> render as a Row. The rest need a find and replace.

The Mintlify column comes from its components overview and callouts page as of September 2026. Custom React components you wrote for Mintlify will not carry across as they are. Scalar MDX supports JSX, expressions, and importing other MDX files, and you can add site-wide HTML, CSS, and JavaScript, so most of them can be rebuilt, but plan for it.

A quick way to size the job:

grep -rhoE "<(Note|Info|Tip|Check|Warning|Danger|CodeGroup|Frame|ParamField|ResponseField|RequestExample|ResponseExample|Mermaid|Tooltip|Badge|Banner|Tree|Update)[ />]" --include="*.mdx" . | sort | uniq -c | sort -rn

Your OpenAPI document does not change. Add it as a route, as in step 2, and Scalar renders one page per operation with the built-in API client for trying requests.

Mintlify reads a few of its own OpenAPI extensions, documented here. They are harmless to leave in the file, but they do nothing in Scalar:

To prefill credentials, which is what x-default did, pass API reference configuration on the route:

"/api-reference": {
  "type": "openapi",
  "title": "API Reference",
  "filepath": "openapi.yaml",
  "config": {
    "authentication": {
      "preferredSecurityScheme": "bearerAuth"
    }
  }
}

Two sets of redirects matter: the ones already in your docs.json, and new ones for any page whose URL changes in the move. API reference pages are the usual culprit, because Scalar generates its own operation URLs. Preview the site, compare it with your current sitemap, and write a rule for every URL that moved.

Mintlify uses source and destination. Scalar uses from and to under siteConfig.routing.redirects:

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/config",
  "scalar": "2.0.0",
  "siteConfig": {
    "routing": {
      "redirects": [
        { "from": "/api-reference/endpoint/get-user", "to": "/api-reference" },
        { "from": "/beta/:pathMatch(.*)*", "to": "/guides/authentication" }
      ]
    }
  }
}

Mintlify's :slug* wildcard becomes :pathMatch(.*)* or :wildcard in Scalar. Mintlify lets you choose a temporary redirect with "permanent": false (docs); Scalar's redirect object has only from and to.

Analytics. Mintlify has built-in integrations for 16 providers under integrations in docs.json. Scalar does not have named integrations. You add the provider's snippet as a script:

"siteConfig": {
  "head": {
    "scripts": [
      { "path": "assets/analytics.js", "defer": true }
    ]
  }
}

Search is on by default. You can move it to the sidebar or turn it off in site config.

AI. Mintlify's assistant is on its Pro plan and above, and it serves a search MCP server at /mcp and an llms.txt. Scalar Docs has all three on by default: Ask AI, a docs MCP server at https://<your-domain>/mcp, and llms.txt and llms-full.txt. Ask AI usage draws on the Agent Scalar credits included with each plan. Separately, Scalar can host an MCP server generated from your OpenAPI document, so agents can call your API rather than only read about it.

Preview locally until it looks right:

npx @scalar/cli project preview

Then connect the repository through Git Sync so every merge publishes. Once published, the site is live on https://<subdomain>.apidocumentation.com, which is a good place to review it with your team before any DNS changes.

Move the custom domain last. On Mintlify, your domain points at cname.mintlify.builders (docs). Add customDomain to siteConfig, publish, and change the CNAME to dns.scalar.com. The record must be DNS-only, so turn off Cloudflare's proxy if you use it. Scalar provisions the certificate on the first request. Custom domains are on Scalar Pro and above. Full details are in Domains.