diff --git a/guides/migration.mdx b/guides/migration.mdx
index 98d0b23c8..58a8629f3 100644
--- a/guides/migration.mdx
+++ b/guides/migration.mdx
@@ -1,14 +1,31 @@
---
title: "Migrations"
-description: "How to migrate documentation from your existing provider"
+description: "How to migrate documentation from your current platform"
icon: "import"
---
-Use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify.
+This guide helps you move your existing documentation to Mintlify. Choose automated migration for supported platforms or manual migration for complete control over the process.
-We currently support automated migration for:
+## Choose your migration path
+
+ If you are migrating from Docusaurus, ReadMe, or GitBook, use our tools to automate your migration.
+
+
+
+ If you are migrating from any other platform, follow our guide to migrate your content.
+
+
+
+
+
+
+Migrate your documentation using the [@mintlify/scraping package](https://www.npmjs.com/package/@mintlify/scraping). The package scrapes your content and converts it to use Mintlify components.
+
+### Supported Platforms
+
+
@@ -78,57 +95,88 @@ We currently support automated migration for:
-} horizontal>
-
-
+} horizontal />
-} horizontal>
-
-
-
+} horizontal />
+
+
+} horizontal />
+
-Don't see your documentation provider or have a custom system? We can still help! Please [contact support](/contact-support).
+If your documentation is hosted on another platform, see the manual migration steps.
-## Commands
+### Installing the scraper
-- `mintlify-scrape section [url]` - Scrapes multiple pages in a site.
-- `mintlify-scrape page [url]` - Scrapes a single page in a site.
+Install the `@mintlify/scraping` package to get started.
-The commands automatically detect the framework.
+```bash
+npm install @mintlify/scraping@latest -g
+```
-## Installation
+### Scraping pages and sections
-You can install the package globally or for one-time use.
+The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default.
-### Global installation
+For large documentation sites, migrate smaller sections at a time rather than the entire site at once.
+**Migrate entire sections:**
```bash
-npm install @mintlify/scraping@latest -g
+mintlify-scrape section https://your-docs-site.com/docs
```
-### One-time use
-
-
+**Migrate single pages:**
+```bash
+mintlify-scrape page https://your-docs-site.com/docs/getting-started
+```
-```bash Section
-npx @mintlify/scraping@latest section [url]
+**Migrate OpenAPI specifications:**
+```bash
+mintlify-scrape openapi-file [openApiFilename]
```
+### Add prepared content to your Mintlify project
-```bash Page
-npx @mintlify/scraping@latest page [url]
-```
+After scraping your existing documentation platform, you are ready to build your docs on Mintlify.
-
+Confirm that all of your pages have been migrated then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.
+
+
-## OpenAPI migration
+Migrate your documentation from any platform with full control over the process.
-Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint.
+### Content migration
-```bash
-mintlify-scrape openapi-file [openApiFilename]
+To migrate your content to Mintlify, you will need:
--w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true]
--o, --outDir The folder in which to write any created frontmatter files [string]
-```
+- A valid `docs.json` for your site settings and navigation. See [Global settings](/settings) and [Navigation](/navigation) for more information.
+- An `MDX` file for each page of your documentation. See [Pages](/pages) for more information.
+- (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information.
+
+1. If your content is already in `MDX` format, copy the pages to your Mintlify project. Otherwise, convert your content to `MDX` format.
+2. Create your `docs.json` referencing the paths to your `MDX` pages.
+3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground.
+
+### Asset migration
+
+1. Copy assets to your repository's `images/` directory.
+2. Update references in your `MDX` files:
+ ```mdx
+ 
+ ```
+
+
+
+
+## Post-migration checklist
+
+After completing your migration (automated or manual), we recommend checking:
+
+- All pages render
+- Navigation works as intended
+- Internal links resolve properly
+- Images and assets load correctly
+- Code blocks display with proper syntax highlighting
+- Search functionality works
+- Deployment is configured
+- Custom domain is set up