How to migrate from Mintlify to open-source docs

Choose the destination before converting content

Start with Mintlify alternatives, then choose one framework for a pilot. Our assessment: evaluate Heyo Docs when MDX and API reference pages are central; Starlight for an Astro documentation site; Docusaurus for a React team considering versioned docs; or VitePress for Markdown and Vue.

Changing the framework also changes the conversion work. A React component will need a different approach in a Vue site. An API reference may need a generator or integration in your chosen stack. Before picking a tool, list the capabilities you cannot lose and prove them on representative pages.

If your only reason to move is the bill, first check Mintlify pricing. Starter may already cover your workflow. A self-hosted site needs someone to own updates, preview builds and incidents even when hosting fits a free allowance.

Inventory the files and the published URLs

Take a snapshot of the documentation repository and record the current public URLs. Include pages generated from API specifications, routes outside the main sidebar, images, downloadable files and redirects. A list of MDX files alone is not a complete inventory.

Mintlify’s global configuration lives in docs.json; older projects may still have mint.json. Configuration can reference other JSON files through $ref. Collect those files as well. Treat the configuration as an inventory of behavior to recreate, rather than a file every alternative understands.

Download the migration inventory CSV. Its rows are illustrative examples, not an export of your site. Replace them with your actual routes, source files, components, owners and results. Keep one row per published page and track shared dependencies separately.

What to collect	Why it matters	What to record in the pilot
MDX and frontmatter	The destination may interpret metadata differently	Title, description, path and rendered output
Navigation configuration	Sidebar order is part of the reader experience	Groups, tabs, languages, versions and external links you use
Components and snippets	Prose can depend on framework-specific behavior	Import paths, nested dependencies and a replacement for each component
OpenAPI files and related settings	Some public pages are generated	Endpoint URLs, examples, auth descriptions and any overlays
Images and downloads	Relative paths can break after a directory move	Source path, public URL and successful loading
Redirects and important deep links	Existing links may target an old path or heading	Old URL, destination, status and fragment checks

Map configuration and navigation

Mintlify’s navigation can organize content through groups, tabs, products, versions and languages. Recreate the structure you actually use in the destination’s configuration; do not flatten everything into one sidebar just because it compiles.

For each route, distinguish its content file from its published URL. Record whether the destination adds a base path, generates a different slug or changes trailing slashes. In the pilot, follow the navigation as a reader would: landing page, guide, API page, then back to the relevant section. Check the active sidebar item and mobile navigation too.

Branding, analytics and authentication are separate tasks. Assign an owner to each setting you carry over. A logo rendering correctly does not show that restricted pages or analytics still work.

Convert components and reusable snippets

Begin with a plain guide, then choose a page with callouts, tabs, code groups and imported snippets. Write down the intended behavior of each component and choose its destination equivalent. Keep code examples, labels and explanations intact while replacing presentation components.

Mintlify supports snippet imports using relative and root-based paths, including nested imports. Audit dependencies recursively: moving a page without the snippet it imports can leave missing content. Check resolved values in both the browser and the initial HTML when the information needs to be available to crawlers.

Use side-by-side rendered pages for review. Check headings, keyboard access, code copying, links, images and narrow screens. A successful build is the first check; it does not prove that a tab panel contains the right content or an imported expression still renders.

Rebuild and review the API reference

Mintlify’s OpenAPI setup can generate endpoint pages from specifications referenced in navigation. Collect those specifications and any configured overlays. Preserve endpoint descriptions and examples, then check how your chosen renderer handles vendor extensions and generated paths.

Include a read endpoint, a write endpoint and an endpoint with authentication in the pilot. Review parameters, required fields, response examples, downloadable specifications and links from written guides. If you need an interactive playground, check its request construction and server configuration using a safe test API. Do not use a production write operation as a documentation smoke test.

Separate documentation coverage from playground parity. An alternative may display the API accurately while needing additional work for interactive requests. The Heyo Docs comparison describes the source-reviewed overlap; it does not establish an automatic conversion.

Preserve paths and translate redirects

Keep existing public paths where practical. Where a page moves, map its old path directly to the closest replacement. Check links to section anchors as well as page URLs; a redirect to the right document can still leave a reader at a missing heading.

Mintlify’s redirects are configured in docs.json and default to permanent 308 responses. Cloudflare’s static asset redirect file uses a different format. For example, this illustrative rule explicitly preserves a permanent status:

/guides/old-install /guides/install 308

Put _redirects in the framework’s public/static directory so it reaches the final asset output. These rules apply to static asset requests; requests served by Worker code need redirects handled in that code or another suitable routing layer. Confirm your chosen framework’s actual request path before relying on the file.

Do not assume wildcard rules translate unchanged. Test exact paths, wildcard captures and deep links. Check for loops and multi-hop redirects. Cloudflare HTML handling also controls trailing-slash behavior based on the configured mode and output layout; verify the final response rather than guessing from filenames.

Run the launch checks on a preview domain

Use a preview deployment before changing DNS. Our Cloudflare setup guide covers choosing a deployment path. The reviewed templates are evidence to inspect, not a tested installer for your documentation.

1. Build every page and check the inventory against the resulting public routes.
2. Verify navigation, search results, snippets, images, downloads and the API reference.
3. Request old URLs and confirm their final destinations and redirect statuses.
4. Inspect page titles, descriptions, canonicals, sitemap URLs and production indexability.
5. Check that authentication requirements and preview access rules behave as intended.
6. Confirm who can publish, how a failed build is detected and how the previous release is restored.

Keep the current site available until the replacement passes your checks. Record the current domain configuration and a rollback procedure. Choose a cutover window when someone can observe the new deployment and fix broken routes.

Measure the move and keep an owner

After launch, check your real search queries, impressions, clicks and indexed pages in Search Console. Compare them with your pre-migration baseline and watch errors on important routes. A redirect checklist helps prevent mistakes; it cannot guarantee preserved rankings.

Review the publishing workflow with the people who write the docs. Make sure they can preview a change, fix a broken build and update API pages without depending on the person who performed the migration. Assign ongoing responsibility for dependency updates, search indexing and usage costs.

Cloudsteading has not performed this migration for a customer or measured its search impact. Use the guide to plan and test your own move, and the reviewed Heyo Docs repository to inspect the original README, license and infrastructure evidence.