From c4651101aa09ed71065fe5db83396ce47b592151 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Jul 2025 15:58:10 -0700 Subject: [PATCH 1/4] Update migration.mdx --- guides/migration.mdx | 112 +++++++++++++++++++++++++++++-------------- 1 file changed, 77 insertions(+), 35 deletions(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index 98d0b23c8..7f1d09292 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,82 @@ 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. This approach works for any platform, complex custom setups, and when you need complete control over the migration. -Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint. +To migrate your content to Mintlify, you will need: -```bash -mintlify-scrape openapi-file [openApiFilename] +- 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. --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] -``` +### Asset migration + +1. **Copy assets** to your repository's `images/` directory +2. **Update references** in your MDX files: + ```mdx + ![Alt text](/images/screenshot.png) + ``` + + + + +## 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 From 8d1bb8a45733a99bcc58f851649c89a861c21955 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Jul 2025 16:03:46 -0700 Subject: [PATCH 2/4] copyedit --- guides/migration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index 7f1d09292..05c47f460 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -143,7 +143,7 @@ Confirm that all of your pages have been migrated then add these files to the do -Migrate your documentation from any platform with full control over the process. This approach works for any platform, complex custom setups, and when you need complete control over the migration. +Migrate your documentation from any platform with full control over the process. To migrate your content to Mintlify, you will need: From 26cb1f2cad2c1bba1f21397cc3e16051932bc416 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 1 Aug 2025 09:45:49 -0700 Subject: [PATCH 3/4] add section header --- guides/migration.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index 05c47f460..44218399e 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -145,6 +145,8 @@ Confirm that all of your pages have been migrated then add these files to the do 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](/settings) and [Navigation](/navigation) for more information. @@ -153,7 +155,7 @@ To migrate your content to Mintlify, you will need: ### Asset migration -1. **Copy assets** to your repository's `images/` directory +1. **Copy assets** to your repository's `images/` directory. 2. **Update references** in your MDX files: ```mdx ![Alt text](/images/screenshot.png) From ef847168360f5bb4617ece8225dd9b04014ab6c5 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 1 Aug 2025 09:53:30 -0700 Subject: [PATCH 4/4] update manual steps --- guides/migration.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/guides/migration.mdx b/guides/migration.mdx index 44218399e..58a8629f3 100644 --- a/guides/migration.mdx +++ b/guides/migration.mdx @@ -153,10 +153,14 @@ To migrate your content to Mintlify, you will need: - 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: +1. Copy assets to your repository's `images/` directory. +2. Update references in your `MDX` files: ```mdx ![Alt text](/images/screenshot.png) ```