Skip to content

migration.mdx

Latest commit

 

History

History
204 lines (139 loc) · 25 KB

migration.mdx

File metadata and controls

204 lines (139 loc) · 25 KB
title Migrate to Mintlify
description Migrate your documentation to Mintlify from Docusaurus, ReadMe, GitBook, or another platform with step-by-step instructions and CLI tooling.
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.

Choose your migration path

  • If you currently use Docusaurus or ReadMe -> Automated migration
  • If you have a public GitHub repository -> Auto-generated migration
  • If you are migrating from any other platform -> Manual migration

Migrate your documentation using the @mintlify/scraping package. The package scrapes your content and converts it to use Mintlify components.

Supported platforms

} horizontal /> } horizontal />

If you host your documentation on another platform, see the manual migration steps.

Installing the scraper

Install the @mintlify/scraping package to get started.

npm install @mintlify/scraping@latest -g

Scraping pages and sections

The migration tool automatically detects your documentation platform and converts your content. It saves prepared files locally in the ./docs folder by default.

For large documentation sites, migrate smaller sections one at a time rather than the entire site at once.

Migrate entire sections:

mintlify-scrape section https://your-docs-site.com/docs

Migrate single pages:

mintlify-scrape page https://your-docs-site.com/docs/getting-started

Filter specific paths:

Use the --filter (or -f) option to scrape only URLs matching a specific path prefix.

mintlify-scrape section https://your-docs-site.com --filter=/docs

The filter matches the specified path and all nested paths. For example, --filter=/docs matches /docs, /docs/getting-started, /docs/api/reference, and so on.

Migrate OpenAPI specifications:

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 you scraped all of your pages. Then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.

Mintlify can generate a complete documentation site for any public GitHub repository, whether it already contains documentation or just code.

Replace github.com with mintlify.com in any public repository URL:

https://mintlify.com/github-owner/repository-name

Mintlify analyzes your repository and generates a complete documentation site that you can further customize.

Migrate your documentation from any platform with full control over the process.

Content migration

To migrate your content to Mintlify, you need:

  • A valid docs.json for your site settings and navigation. See Global settings and Navigation for more information.
  • A Markdown file (.md or .mdx) for each page of your documentation. MDX is the recommended format. See Pages for more information.
  • (Optional) An OpenAPI specification for your API endpoint pages. See OpenAPI setup for more information.
  1. If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format.
  2. Create your docs.json referencing the paths to your Markdown pages.
  3. If you have OpenAPI specifications, add them to your docs.json and configure the API playground. You can also generate MDX pages from your spec using the @mintlify/scraping package:
npx @mintlify/scraping@latest openapi-file <openApiFilename> -o <folder-name>
If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components.

Asset migration

  1. Copy assets to your repository's images/ directory.
  2. Update references in your Markdown files: 
    ![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 works
  • Correct deployment branch