Migrate from another platform - Mintlify
Use a Manual Migration
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.
- Markdown or MDX files from your source repository
- A native Markdown or HTML export from your current platform
- Content retrieved through your current platform’s API
- Rendered HTML from your published site
- 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.jsonfile 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
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.
| Content model | Mintlify navigation elements |
|---|---|
| One documentation set | Groups and pages |
| Distinct products | Products |
| Major content areas | Tabs or anchors |
| Supported releases | Versions |
| Translated documentation | Languages |
| Group overview | A group with a root page |
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.
| Source pattern | Mintlify feature |
|---|---|
| Note, tip, warning, or danger block | Callout |
| Collapsible section | Accordion |
| Alternative instructions | Tabs |
| Multiple code examples | Code group |
| Linked resource tiles | Cards |
| Sequential procedure | Steps |
| Reused content | Reusable snippet |
| Interactive or application-specific UI | React component |
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.
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
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. 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. Install any required analytics integrations, and optionally add a custom 404 page.