How to Migrate From Mintlify Without Rewriting Your MDX

To move off Mintlify without rewriting your MDX, use a host that reads Mintlify's project format as it is. Docs7 does: connect the same GitHub repository and it builds your docs.json (or older mint.json), MDX pages, snippets, OpenAPI files, and redirects, then gives you a preview before you change DNS. If cost is the only reason to leave, Mintlify's own free Starter plan is worth a look. Moving to GitBook, Fern, or an open-source framework like Docusaurus means converting to that tool's format.

The move takes four steps: check the repository, connect it, compare the preview with your live site, and switch the domain. Most of the work is the checking, because component coverage is not guaranteed and some things live in Mintlify's dashboard, not your repository.

Step 1: Check That Your Repository Is Ready

Docs7 builds from a GitHub repository. Confirm four things before you connect it.

Find the config file. Mintlify replaced mint.json with docs.json, and Docs7 reads either one. It looks for docs.json first, then mint.json, in the folder you point it at. Note that folder: usually the repository root, or a folder like docs in a monorepo.

Make sure the repository is yours. If you skipped connecting your own Git repository when you set up Mintlify, your docs live in a private repository owned by the Mintlify organization. Clone it into your GitHub account from Mintlify's Git Settings page first.

Publish or discard pending changes in Mintlify's web editor. Edits there only reach your repository when you publish them, and only what is in Git moves.

Check whether the repository is public or private. Docs7 Free hosts up to three sites from public repositories; private repositories need Pro. Docs7 connects GitHub repositories only. Its CLI can deploy a folder without GitHub, but a CLI site stays on its docs7.io address, with no custom domain or pull request previews, so a migration needs the GitHub connection.

To see how Docs7 renders your pages before you connect anything, run the Docs7 CLI from the docs folder. It needs Node.js 20.19 or newer.

$ npx @upstash/docs7 dev

Step 2: Connect the Repository and Get a Preview Build

Open context7.com/docs7/add and sign in. Keep Host on Docs7 selected. Click Connect GitHub if asked, and give the Context7 GitHub App access to the repository. Pick the repository, then set the branch (usually the one Mintlify deploys from) and the docs path from step 1. Leave Add to Context7 ticked if you want the docs indexed on Context7, then click Add.

Docs7 checks the folder for docs.json or mint.json. If it finds one, hosting turns on and the first build starts. If the folder has neither, the repository connects for agent features only and no site is built, which usually means the docs path is wrong.

When the build finishes, the new site is live at its docs7.io address. That is your preview. Your readers see no change: Mintlify still serves your custom domain.

Step 3: Compare the Preview With Your Live Mintlify Site

Open the build on the Builds tab and read its health report first. A component Docs7 does not recognize is reported as a warning, not a failure, so a build can succeed while a page renders differently. Treat each warning as a page to look at.

Then put the preview and your live Mintlify site side by side. Start with the home page, the quickstart, your most visited guides, and the API reference. Check navigation, tabs, code blocks, callouts, cards, and images. Docs7 implements nine Mintlify themes (mint, maple, palm, willow, linden, almond, aspen, sequoia, and luma) and reads the theme field in docs.json. If your docs.json sets a theme outside that list, Docs7 renders the site with mint and the layout will look different.

Redirects get their own pass. Mintlify keeps them in the redirects field of docs.json, and Docs7 reads that list. Try a handful of old URLs on the preview.

If your API reference is generated from an OpenAPI file, open several endpoints and check parameters, examples, and the API playground.

Snippets and custom components are the most likely to differ. Mintlify keeps custom React components as .jsx files in the snippets folder. Check every page that uses one.

Fix what you find in the repository. Each push to the production branch builds again. Mintlify builds from the same repository, so keep fixes compatible with both until you switch.

Step 4: Move the Custom Domain Last, Then Turn On the Extras

Switch the domain only when the preview looks right. Until then, Mintlify keeps serving your readers.

Add the domain in the Domain card on the site's Settings tab. Docs7 supports two setups. Its own domain, such as docs.example.com, uses DNS records that Docs7 lists for you: add the TXT records first, then change the CNAME when you are ready to switch. Keep that CNAME unproxied (sometimes called DNS only), or the certificate may not be issued. A path on an existing site, such as example.com/docs, uses a reverse proxy rule, and Docs7 shows the configuration for Cloudflare, Vercel, AWS, and other proxies.

If your Mintlify plan includes analytics, export the data you want to keep before you cancel. Mintlify exports traffic, referrals, assistant conversations, searches, and feedback to CSV.

Then change the CNAME or turn on the proxy rule. Docs7 issues the HTTPS certificate a few minutes after the CNAME points at it, so switch at a quiet time. Spot-check the same pages and redirects on the real domain. Keeping the same domain and paths reduces SEO risk. Once you are confident, cancel Mintlify and remove its GitHub App from the repository, so a push no longer deploys to both.

With the site live, three features are worth a look.

Add to Context7

Best for: Coding agents that read your docs

The site becomes a Context7 library, refreshed on every successful production deploy, so coding agents using the Context7 MCP server get your current docs. Disconnecting stops the refreshes.

Pull request previews

Best for: Reviewing docs changes before they ship

On by default, on both plans. Opening or updating a pull request that changes the docs builds a preview, and closing it removes the preview. Each build is reported as a GitHub Check Run.

PR Review Agent

Best for: Catching broken links and build issues in pull requests

It checks preview builds for broken links, spelling and grammar, and build health issues. It is off by default, starts by commenting, and can also open fix pull requests.

AI agents that keep docs up to date →

What Should You Check Before Switching DNS?

Use this checklist for the whole migration. Each row has a clear finish line.

What Does Not Carry Over From Mintlify?

Your content moves because it lives in Git. Anything that lives only in Mintlify's dashboard, such as settings and team seats, does not. Check these by hand.

Component coverage. There is no guarantee every component renders exactly as on Mintlify. The preview and its warnings are the test that counts.

The web editor. Docs7 has no web editor. Editing happens in Git and MDX, so anyone who wrote in Mintlify's editor needs a Git workflow.

Analytics history. Mintlify's traffic, search, feedback, and assistant data stays with Mintlify, so export it before you cancel. Docs7 analytics starts the day you switch, with 7 days of history on Free and 90 on Pro.

Mintlify's hosted MCP server. Mintlify generates a search MCP server at the /mcp path of your site. If people connected agents to that URL, tell them about the change. On Docs7, agents read your docs through llms.txt and markdown pages, and, with Add to Context7, through the Context7 MCP server.

Why Some Teams Stay on Mintlify

Moving is not always the right call. These are fair reasons to stay.

Non-developers write the docs

Best for: Teams that edit in the browser

Mintlify's web editor is on every plan, including the free Starter plan. Docs7 is Git and MDX only, with no web editor.

Your docs require login

Best for: Private customer or partner docs

Mintlify can put docs behind a login: password protection on Pro, and OAuth or JWT on Enterprise. Docs7 does not offer login-protected docs.

Your repository is not on GitHub

Best for: Teams on GitLab or Bitbucket

Mintlify deploys from GitLab as well as GitHub, and from Bitbucket Cloud on Enterprise. Docs7 connects GitHub repositories only. Its CLI can deploy a folder from anywhere, but that site stays on a docs7.io address, without a custom domain or pull request previews.

You rely on Mintlify-only features

Best for: Teams deep in the Mintlify dashboard

AI translations, Mintlify's own agent and automations, and its hosted MCP server do not move with the repository. If you depend on them, compare carefully first.

Nothing is wrong

Best for: Teams happy with the site and the bill

A migration still means a round of checking and a DNS change. Without a concrete reason to leave, staying is fine.

Frequently asked questions

I want to move off Mintlify without rewriting my MDX. What can I use?

Use a host that reads Mintlify's docs.json format directly. Docs7 builds an existing Mintlify repository as it is, including MDX, snippets, OpenAPI files, and redirects, and gives you a preview before you switch your domain. GitBook, Fern, and Docusaurus use their own formats, so moving there means converting content and replacing components.

Is there a free alternative to Mintlify?

Docs7 has a free plan that hosts up to three sites from public GitHub repositories, with a custom domain, pull request previews, agent and human analytics, Context7 integration, WebMCP search, the API playground, and limited use of the AI assistant, the Context7 Agent, and PR reviews. Free sites show a footer attribution, and private repositories need Pro. Mintlify's own Starter plan is also free and includes a custom domain, the web editor, and an MCP server, but not analytics, the assistant, or preview deployments.

Does Docs7 work with mint.json or only docs.json?

Both. Docs7 looks for docs.json first and falls back to mint.json in the docs folder you choose. Mintlify has deprecated mint.json in favor of docs.json, so upgrading is worth doing eventually, but you do not need to upgrade to move.

Will my Mintlify components work on Docs7?

Docs7 is built to be Mintlify-compatible, but there is no guarantee every component renders identically. It implements nine Mintlify themes and renders any other theme with mint. Components Docs7 does not recognize show up as build warnings instead of failing the build. Read your first build's health report and compare those pages with your live site, starting with custom React components.

Will I lose SEO if I migrate from Mintlify?

Keeping the same domain and URL paths reduces the risk. Docs7 generates canonical metadata, sitemap.xml, robots.txt, and the permanent redirects defined in your docs.json. Test a sample of old URLs on the preview before you switch DNS, and again on the real domain after.

Can I go back to Mintlify if the migration goes wrong?

Yes, as long as your Mintlify project is still active with your custom domain set up. Docs7 builds the same repository Mintlify does, so rolling back means pointing your DNS at Mintlify again. That is why you keep Mintlify running until the Docs7 site has served real traffic for a while.

Get a Preview Before You Touch DNS

Connect the GitHub repository Mintlify builds from today, review the Docs7 preview and its warnings, and switch your domain only when the pages match.

• Connect your docs repository
• See Docs7 pricing