> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mintlify/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Mintlify

> Learn how to migrate to Mintlify from Docusaurus, ReadMe, or another platform.

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

<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

    Mintlify provides automated migration tools for the following platforms:

    <CardGroup cols={2}>
      <Card title="Docusaurus" icon="book">
        Automatically convert your Docusaurus site to Mintlify format
      </Card>

      <Card title="ReadMe" icon="book-open">
        Import your ReadMe documentation with full component support
      </Card>
    </CardGroup>

    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 theme={null}
    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.

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

    **Migrate entire sections:**

    ```bash theme={null}
    mintlify-scrape section https://your-docs-site.com/docs
    ```

    **Migrate single pages:**

    ```bash theme={null}
    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.

    ```bash theme={null}
    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.

    You can also use the CLI command:

    ```bash theme={null}
    mint scrape site https://your-docs-site.com --filter=/docs
    ```

    **Migrate OpenAPI specifications:**

    ```bash theme={null}
    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.

    <Steps>
      <Step title="Verify migration">
        Confirm that all of your pages have been migrated successfully. Review the generated files in the `./docs` directory.
      </Step>

      <Step title="Add to repository">
        Add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.
      </Step>

      <Step title="Deploy">
        Push your changes to deploy your migrated documentation to Mintlify.
      </Step>
    </Steps>
  </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 need:

    * A valid `docs.json` for your site settings and navigation. See [Global settings](/organize/settings) and [Navigation](/organize/navigation) for more information.
    * A Markdown file (`.md` or `.mdx`) for each page of your documentation. MDX is the recommended format. 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.

    <Steps>
      <Step title="Convert content">
        If your content is already in Markdown format, copy the content to your Mintlify project. Otherwise, convert your content to MDX format.
      </Step>

      <Step title="Create docs.json">
        Create your `docs.json` referencing the paths to your Markdown pages.
      </Step>

      <Step title="Add OpenAPI specs">
        If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground.
      </Step>
    </Steps>

    <Tip>
      If you migrate your content as `.md` files, convert them to `.mdx` to support interactive features like React components.
    </Tip>

    ### Asset migration

    <Steps>
      <Step title="Copy assets">
        Copy assets to your repository's `images/` directory.
      </Step>

      <Step title="Update references">
        Update references in your Markdown files:

        ```mdx theme={null}
        ![Alt text](/images/screenshot.png)
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Post-migration checklist

After completing your migration (automated or manual), we recommend checking:

<AccordionGroup>
  <Accordion title="Content validation">
    * All pages render correctly
    * Navigation works as intended
    * Internal links resolve properly
  </Accordion>

  <Accordion title="Assets and media">
    * Images and assets load correctly
    * Code blocks display with proper syntax highlighting
  </Accordion>

  <Accordion title="Functionality">
    * Search works
    * Deployment is configured
    * Custom domain is set up (if applicable)
  </Accordion>
</AccordionGroup>

<Warning>
  Test your documentation thoroughly before directing users to your new Mintlify site.
</Warning>