mintlify__docs/migration/manual.mdx

---
title: "Migrate from another platform"
description: "Convert documentation from any source platform to Mintlify pages, navigation, components, API references, assets, and redirects."
keywords: ["manual documentation migration", "Markdown migration", "MDX migration", "docs.json"]
---

import MigrationLaunchChecklist from "/snippets/migration-launch-checklist.mdx";

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](/organize/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](/organize/navigation). 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](/organize/hidden-pages) 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](/components/callouts) |
| Collapsible section | [Accordion](/components/accordions) |
| Alternative instructions | [Tabs](/components/tabs) |
| Multiple code examples | [Code group](/components/code-groups) |
| Linked resource tiles | [Cards](/components/cards) |
| Sequential procedure | [Steps](/components/steps) |
| Reused content | [Reusable snippet](/create/reusable-snippets) |
| Interactive or application-specific UI | [React component](/customize/react-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.

- [OpenAPI setup](/api-playground/openapi-setup)
- [AsyncAPI setup](/api-playground/asyncapi-setup)
- [GraphQL setup](/api-playground/graphql-setup)

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:

```bash
npx @mintlify/scraping@latest openapi-file ./openapi.yaml -o api-reference
```

## 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](/create/redirects) 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.

<MigrationLaunchChecklist />