Migrate from Mintlify

Move Mintlify documentation to ReadMe by importing public content for evaluation or migrating your MDX repository through Git-based import or rdme@10. Both platforms give you an OpenAPI-generated API Reference with Try It!, an embedded AI assistant, and Git-backed content review — moving to ReadMe means running your Guides, API Reference, Changelog, and Recipes on one platform, with usage data tied to individual developers in My Developers.

Choose the easiest migration path

Your situation	Recommended path
You want to preview how public content appears in ReadMe	Use the Importer with your documentation URL, Markdown, or OpenAPI definition.
You have the Mintlify repository	Prepare the content for Git-based import or use `rdme@10` for a controlled scripted upload.
You have only a few pages	Create and review them in the ReadMe editor.
You have extensive custom MDX, API navigation, versions, or complex content governance	Ask about Enterprise migration assistance.

Use bi-directional Git Sync after migration when you want ongoing two-way editing. It requires a new, empty GitHub or GitLab repository; it does not import an existing Mintlify repository.

What doesn't transfer, and what replaces it

What doesn't transfer	Rebuild it with
Custom React components and JSX	Custom MDX components
Hand-written `<ParamField>` and `<ResponseField>` pages	An API Reference generated from your OpenAPI file, with Try It!
Theme configuration from `docs.json` (colors, fonts, logo, layout)	Reconfigure with ReadMe Themes and Appearance settings — settings don't carry over automatically, but comparable customization is available
Mintlify's Ask AI configuration (starter questions, deflection email, tone controls)	Reconfigure with Ask AI, ReadMe's embedded assistant — settings and indexed content don't carry over automatically
Mintlify's page-view analytics integrations (GA4, Mixpanel, PostHog, and similar)	ReadMe's Metrics SDK and Developer Dashboard, which tie API request logs to individual developers rather than page views alone
Mintlify's suggesting mode and PR-based review	ReadMe Branches and Reviews — review continues in ReadMe's workflow instead of Mintlify's editor

Inventory your Mintlify site

Copy the repository and keep the original unchanged.
Preserve docs.json; it is the source for navigation, configuration, and OpenAPI entries.
Inventory MDX pages, assets, snippets, custom JSX, custom components, endpoint pages, and OpenAPI files.
Record public URLs for high-traffic pages and every version, group, tab, dropdown, and API Reference entry you plan to retain.

Convert content and navigation

Mintlify	ReadMe
`title`	`title`
`description`	`excerpt`
`icon`	Convert to a supported Font Awesome class.
`noindex: true`	`metadata.robots: noindex`
`sidebarTitle`	Preserve it as the intended page or navigation title.
`openapi`	Upload the API definition separately.
`mode`	Remove.

Convert components one type at a time and verify the result before applying a bulk replacement. Map callouts, tabs, cards, accordions, columns, code groups, steps, and frames only when ReadMe supports the needed syntax and props. Rewrite custom JSX, tooltips, badges, and updates when they do not have an equivalent implementation.

Use docs.json as the source of navigation. For CLI uploads, each new Guide needs title and category.uri; use position and parent.uri to reproduce navigation. For Git-based import, prepare the supported folder structure and _order.yaml files. Review OpenAPI navigation entries separately because they represent generated operations rather than MDX pages.

Upload OpenAPI and Guides

Validate and upload the OpenAPI definition, then compare generated API Reference pages with Mintlify endpoint content:

npx rdme@10 openapi validate ./openapi.yaml
npx rdme@10 openapi upload ./openapi.yaml --key="$README_API_KEY"
npx rdme@10 docs upload ./docs --key="$README_API_KEY" --dry-run

Resolve reported errors, then upload Guides without --dry-run. Keep conceptual workflows and examples that do not exist in the OpenAPI definition as Guides. Configure authentication before testing Try It!, and integrate the Metrics SDK separately if you need API-log data in the Developer Dashboard.

Set up redirects and cut over

Build redirects from published Mintlify URLs, docs.json, and traffic data. Under Admin Settings > Error Pages, add rules as oldurl -> newurl, one per line. Verify MDX rendering, assets, navigation, retained versions, API Reference coverage, and high-traffic redirects before changing your domain.

Keep Mintlify available while you verify the migration and complete cutover.

Optional: continue in Git

After migration, connect a new empty repository through Settings > Git Connection to enable bi-directional Git Sync. Use folders and _order.yaml files to manage navigation in that workflow.

After you migrate

Run a Docs Audit to check content quality, build guided walkthroughs with Recipes, and use My Developers to see how developers use your API once your Metrics integration is live.

Frequently asked questions

Can we migrate hand-written Mintlify endpoint pages?

Review each page against the generated ReadMe API Reference. Retain information that is not present in the OpenAPI definition as Guides rather than deleting it.

Do we have to move our API Reference and Guides at the same time?

No. Uploading your OpenAPI definition is independent. Some teams stand up the API Reference first, run it alongside their existing Mintlify guides for a period, and migrate the guides after.

What happens to pages that were hidden or unpublished?

They migrate like any other file. Set hidden: true in frontmatter to keep them unpublished on ReadMe.

Can we continue editing in Git?

Yes. After the migration is complete, you can enable bi-directional Git Sync with a new empty GitHub or GitLab repository for ongoing two-way editing.