Skip to content

Migration guide update #961

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 1, 2025
Merged

Migration guide update #961

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c465110
Update migration.mdx
ethanpalm Jul 25, 2025
8d1bb8a
copyedit
ethanpalm Jul 25, 2025
26cb1f2
add section header
ethanpalm Aug 1, 2025
ffad795
Merge branch 'main' into migration-guides
ethanpalm Aug 1, 2025
ef84716
update manual steps
ethanpalm Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 83 additions & 35 deletions guides/migration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<CardGroup cols="2">
<Card title="Automated migration" icon="wand-sparkles">
If you are migrating from Docusaurus, ReadMe, or GitBook, use our tools to automate your migration.

Check warning on line 13 in guides/migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

guides/migration.mdx#L13 

Did you really mean 'Docusaurus'?
</Card>

<Card title="Manual migration" icon="pencil-ruler">
If you are migrating from any other platform, follow our guide to migrate your content.
</Card>
</CardGroup>

<Tabs>
<Tab title="Automated migration">

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

<Columns cols="3">
<Card title="Docusaurus" icon={<svg className="h-6 w-6" width="36" height="36" viewBox="0 -19 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid">
<g>
<rect fill="#FFFFFF" x="126.030769" y="45.9487179" width="110.276923" height="44.6358974">
Expand Down Expand Up @@ -78,57 +95,88 @@

</path>
</g>
</svg>} horizontal>

</Card>
</svg>} horizontal />
<Card title="ReadMe" icon={<svg fill="#177fc4" className="h-6 w-6" width="36" height="36" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
<path d="M29.35 4.361h-7.767c-2.672 0-4.994 1.85-5.578 4.461-0.589-2.611-2.906-4.461-5.578-4.461h-7.761c-1.472 0-2.667 1.194-2.667 2.667v13.656c0 1.472 1.194 2.667 2.667 2.667h4.983c5.678 0 7.372 1.355 8.183 4.167 0.039 0.156 0.289 0.156 0.333 0 0.817-2.811 2.511-4.167 8.183-4.167h4.983c1.472 0 2.667-1.194 2.667-2.667v-13.65c0-1.467-1.183-2.661-2.65-2.672zM13.444 19.105c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 15.722c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.106 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 12.339c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM27.85 19.1c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 15.717c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 12.333c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.267c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.267z"/>
</svg>} horizontal>

</Card>
</CardGroup>
</svg>} horizontal />
<Card title="GitBook (beta)" icon={<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" height="24" width="24">
<path d="M12.513 1.097c-0.645 0 -1.233 0.34 -2.407 1.017L3.675 5.82A7.233 7.233 0 0 0 0 12.063v0.236a7.233 7.233 0 0 0 3.667 6.238L7.69 20.86c2.354 1.36 3.531 2.042 4.824 2.042 1.292 0.001 2.47 -0.678 4.825 -2.038l4.251 -2.453c1.177 -0.68 1.764 -1.02 2.087 -1.579 0.323 -0.56 0.324 -1.24 0.323 -2.6v-2.63a1.04 1.04 0 0 0 -1.558 -0.903l-8.728 5.024c-0.587 0.337 -0.88 0.507 -1.201 0.507 -0.323 0 -0.616 -0.168 -1.204 -0.506l-5.904 -3.393c-0.297 -0.171 -0.446 -0.256 -0.565 -0.271a0.603 0.603 0 0 0 -0.634 0.368c-0.045 0.111 -0.045 0.282 -0.043 0.625 0.002 0.252 0 0.378 0.025 0.494 0.053 0.259 0.189 0.493 0.387 0.667 0.089 0.077 0.198 0.14 0.416 0.266l6.315 3.65c0.589 0.34 0.884 0.51 1.207 0.51 0.324 0 0.617 -0.17 1.206 -0.509l7.74 -4.469c0.202 -0.116 0.302 -0.172 0.377 -0.13 0.075 0.044 0.075 0.16 0.075 0.392v1.193c0 0.34 0.001 0.51 -0.08 0.649 -0.08 0.14 -0.227 0.224 -0.522 0.394l-6.382 3.685c-1.178 0.68 -1.767 1.02 -2.413 1.02 -0.646 0 -1.236 -0.34 -2.412 -1.022l-5.97 -3.452 -0.043 -0.025a4.106 4.106 0 0 1 -2.031 -3.52V11.7c0 -0.801 0.427 -1.541 1.12 -1.944a1.979 1.979 0 0 1 1.982 -0.001l4.946 2.858c1.174 0.679 1.762 1.019 2.407 1.02 0.645 0 1.233 -0.34 2.41 -1.017l7.482 -4.306a1.091 1.091 0 0 0 0 -1.891L14.92 2.11c-1.175 -0.675 -1.762 -1.013 -2.406 -1.013Z" fill="#currentColor" stroke-width="1"></path>
</svg>} horizontal />
</Columns>

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

<CodeGroup>
**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.

</CodeGroup>
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.
</Tab>
<Tab title="Manual migration">

## 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
![Alt text](/images/screenshot.png)
```

</Tab>
</Tabs>

## 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