Skip to main content
Use a manual migration when your current platform is not included in the listed platforms, your site is private, or you need complete control over the resulting structure.

​
Collect your source content

Export or copy all content before converting it.
  1. Markdown or MDX files from your source repository
  2. A native Markdown or HTML export from your current platform
  3. Content retrieved through your current platform’s API
  4. Rendered HTML from your published site
  5. Manual copy and conversion
Keep your original export unchanged. Perform conversion work in a copy so you can compare or restart your migration. Create an inventory containing each page’s source identifier, title, published URL, destination path, content type, version, language, and migration status. Include unpublished pages that should remain available.

​
Create your Mintlify project

A typical Mintlify project includes:
  • A docs.json file for site settings and navigation
  • Markdown or MDX files for pages that are not generated from an API specification
  • Images and downloadable files that you want to host from your repository
  • Optional OpenAPI or AsyncAPI specifications or GraphQL schemas for generated API documentation
See Pages for supported frontmatter and file behavior.

​
Design your navigation

You can faithfully reproduce your existing navigation structure or use the migration as an opportunity to improve how users find content. Use an appropriate navigation structure. The following table shows common navigation patterns for sites hosted on Mintlify. Add every page path to docs.json unless you intend to hide the page. A hidden page remains reachable by URL, but it is excluded from site search, sitemaps, search engine indexing, and AI context by default.

​
Convert your content

Plain Markdown usually needs little conversion. Replace platform-specific syntax with Mintlify components. Search your converted files for source-platform directives, imports, templating variables, raw HTML, and unresolved includes. These patterns often render as text or fail during an MDX build.

​
Migrate API documentation

Locate the original OpenAPI or AsyncAPI specification or GraphQL schema when one exists. Add the source file to your Mintlify repository and follow the relevant setup guide. If your source platform stored endpoint descriptions outside the specification, merge useful content into the specification or place it in adjacent guides. Compare operation order, authentication, server URLs, examples, schemas, and code samples with your former site. You can generate initial OpenAPI endpoint pages with the Mintlify scraper package:

​
Migrate your assets

Copy images, videos, fonts, and downloadable files that you own into your repository. Preserve existing public paths where practical to reduce link changes. Review the following patterns to identify assets that need to be migrated.
  • Markdown image and link destinations
  • HTML <img> and <video> elements
  • CSS background images
  • Assets referenced by imported components
  • Files hosted by your former documentation provider
  • Version-specific and language-specific assets
Do not leave required production assets on your former provider’s domain unless you plan to retain that hosting after migration.

​
Preserve URLs

Create a mapping from every former published URL to its destination. Add a redirect whenever the pathname changes. Include the following patterns in your redirect mapping.
  • Pages removed or consolidated during migration
  • Version and language prefixes
  • Category or space prefixes
  • Custom landing pages
  • API endpoint pages
  • Explicit slugs and legacy aliases

​
Recreate your site features

Content exports do not normally include platform configuration. Inventory and recreate the features you still need.
  • Custom domain and DNS
  • Authentication and page visibility
  • Analytics and tag managers
  • Search behavior
  • Custom scripts and styling
  • Feedback and support integrations
  • Changelogs
  • SEO metadata, canonical URLs, and indexing rules

​
Review your migration

Compare your migrated project against your content inventory, then confirm that every intended page, version, and language resolves. Search your converted files for leftover source-platform syntax: directives, imports, templating variables, raw HTML, and unresolved includes.

​
Launch your new site

  • Set a content freeze on your former site and track every change made to it after your migration snapshot.
  • Confirm your production branch and repository on the Git settings page of your dashboard.
  • Record your existing DNS records and keep your former site running until you verify your Mintlify deployment is live.
  • Review the navbar, footer, favicon, logo, colors, and typography.
  • Review site and page metadata, canonical URLs, and indexing preferences. See SEO and search settings.
  • Install any required analytics integrations, and optionally add a custom 404 page.
  • If you migrated an API reference, compare endpoint pages, navigation structure, server URLs, authentication schemes, and examples with your former site.
  • Preview your exact launch commit in a preview deployment. Check desktop and mobile layouts, pages from every navigation section, search, and your redirects.
  • Check the browser console and network tab for any errors on pages that use custom components or scripts.
  • Switch your domain with the custom domain guide, which covers the zero-downtime cutover for a domain that already serves documentation.
  • After launch, monitor for 404 errors, redirect failures, and build failures.

Related topics

Migrate from Document360Migrate from FernMigration overview