mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
105 lines
3.7 KiB
Plaintext
105 lines
3.7 KiB
Plaintext
---
|
|
title: "Migrations"
|
|
description: "Learn how to migrate to Mintlify from Docusaurus, ReadMe, or another platform."
|
|
keywords: ["migration","Docusaurus","ReadMe","import"]
|
|
---
|
|
|
|
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.
|
|
|
|
hgello there
|
|
|
|
## Choose your migration path
|
|
|
|
<CardGroup cols="2">
|
|
<Card title="Automated migration" icon="wand-sparkles">
|
|
If you are migrating from Docusaurus or ReadMe, use our tools to automate your migration.
|
|
</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
|
|
|
|
If your documentation is hosted on another platform, see the manual migration steps.
|
|
|
|
### Installing the scraper
|
|
|
|
Install the `@mintlify/scraping` package to get started.
|
|
|
|
```bash
|
|
npm install @mintlify/scraping@latest -g
|
|
```
|
|
|
|
### Scraping pages and sections
|
|
|
|
The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default.
|
|
|
|
For large documentation sites, migrate smaller sections at a time rather than the entire site at once.
|
|
|
|
**Migrate entire sections:**
|
|
|
|
```bash
|
|
mintlify-scrape section https://your-docs-site.com/docs
|
|
```
|
|
|
|
**Migrate single pages:**
|
|
|
|
```bash
|
|
mintlify-scrape page https://your-docs-site.com/docs/getting-started
|
|
```
|
|
|
|
**Migrate OpenAPI specifications:**
|
|
|
|
```bash
|
|
mintlify-scrape openapi-file [openApiFilename]
|
|
```
|
|
|
|
### Add prepared content to your Mintlify project
|
|
|
|
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.
|
|
</Tab>
|
|
<Tab title="Manual migration">
|
|
Migrate your documentation from any platform with full control over the process.
|
|
|
|
### Content migration
|
|
|
|
To migrate your content to Mintlify, you will need:
|
|
|
|
- A valid `docs.json` for your site settings and navigation. See [Global settings](/organize/settings) and [Navigation](/organize/navigation) for more information.
|
|
- An `MDX` file for each page of your documentation. See [Pages](/organize/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
|
|
|
|
```
|
|
</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 |