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

# Migrate from ReadMe

> Migrate ReadMe guides, API references, recipes, custom pages, versions, reusable content, and assets to Mintlify with the scraper or a project export.

Migrate a public ReadMe project with the Mintlify scraper, or export project files from ReadMe when you need private content, OpenAPI specifications, or multiple versions.

## Choose a method

| Method               | Use it when                                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Scraper              | Your complete ReadMe site is public and you want the fastest conversion of rendered pages and navigation.                            |
| ZIP or GitHub export | You can access your ReadMe project and need private pages, OpenAPI files, custom pages, recipes, or multiple documentation versions. |
| ReadMe API           | You need data that your file export does not include, such as hosted images or other project data.                                   |

For a complete migration, start with a native export and use a scrape of your public site as a comparison. The two inventories help reveal your unpublished pages and content that does not have a file representation.

## Export from ReadMe

From the branch menu in ReadMe, export the documentation files as a ZIP. ReadMe sends the completed export by email. The exported project structure can include guides, recipes, custom pages, custom blocks, API Reference content, and OpenAPI files, but it does not include the image files themselves.

If your project uses ReadMe's GitHub integration, you can export your project to a repository. ReadMe documents that the repository contains the same content as a branch export and can include all documentation versions.

Keep your export unchanged as a migration snapshot. Do conversion work in a copy or on a separate Git branch.

<Warning>
  Export every maintained version before deleting or changing anything in ReadMe. Also export or download hosted images separately. Your file export preserves their paths but not the image files.
</Warning>

## Migrate a public site

<Warning>
  The scraper can overwrite existing files.

  Run the scraper in an empty directory so it does not replace any existing files.
</Warning>

```bash theme={null}
mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://your-project.readme.io
```

If your site contains documentation under a specific path or version, use a filter to limit the initial migration:

```bash theme={null}
npx @mintlify/scraping@latest section https://your-project.readme.io --filter=/docs
```

The scraper converts reachable pages, images, navigation, and common rendered components. It cannot access your private or unpublished content and does not replace a separate export of your source OpenAPI specification.

## Understand your exported files

ReadMe's file structure generally separates content by type.

```text theme={null}
docs/             Guides organized by category
reference/        API reference pages and OpenAPI files
recipes/          Step-by-step recipes
custom_pages/     Markdown or HTML custom pages
custom_blocks/    Reusable custom blocks
_order.yaml       Order within a folder or category
```

A folder containing child pages can include `index.md` for the parent page and `_order.yaml` for its children. Translate that structure to nested `group` and `pages` entries in `docs.json`. Use the parent `index.md` as the group's `root` when it contains useful overview content.

| ReadMe                        | Mintlify                              |
| ----------------------------- | ------------------------------------- |
| Guide category                | Navigation group                      |
| `_order.yaml`                 | Order of the `pages` array            |
| Folder `index.md`             | Group `root` page                     |
| Guide or reference child page | Nested group or page                  |
| Project version or branch     | Navigation version                    |
| Custom Page                   | Standard MDX page or custom layout    |
| Link page                     | Navigation link or a redirecting page |

See [Navigation](/docs/organize/navigation) for more information on how to structure navigation elements.

## Convert pages and frontmatter

Retain `title`, SEO metadata, descriptions, and useful keywords. Convert ReadMe-specific fields.

| ReadMe frontmatter                          | Mintlify treatment                                                                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `excerpt`                                   | Use as the page `description`.                                                                                                                                                  |
| `hidden: true`                              | Leave the page out of navigation and review whether it should remain reachable.                                                                                                 |
| `deprecated: true`                          | Add a deprecation warning to the page.                                                                                                                                          |
| `metadata.title` and `metadata.description` | Compare them with the visible `title` and `excerpt`. Choose which values to use for the Mintlify `title` and `description`, and use Open Graph fields only for social previews. |
| `metadata.robots: noindex`                  | Set `noindex: true`.                                                                                                                                                            |
| `next.pages`                                | Add explicit links or related-page cards where they help the reader.                                                                                                            |
| `icon` with Font Awesome classes            | Replace with a supported Font Awesome, Lucide, or Tabler icon name.                                                                                                             |

ReadMe supports a custom Markdown dialect and JSON-based magic blocks. The scraper converts common rendered components, but file exports can retain platform syntax. Review the following patterns to identify content that must be converted.

* Callouts, tabs, accordions, cards, and code groups
* Reusable Content and Custom Blocks
* Variables and glossary terms
* Interactive recipes
* Custom HTML pages
* Embedded API explorers and personalized content

Convert reusable material to [Mintlify snippets](/docs/create/reusable-snippets). Your export might expand a reusable block into each page, so compare the copies and consolidate only identical content.

## Migrate API reference content

Prefer your original OpenAPI file over rendered or exported endpoint pages.

1. Find every JSON or YAML OpenAPI file in `reference/` and any source repository that you used with `rdme` or ReadMe's API sync.
2. Identify Markdown that editors added in ReadMe outside the specification. ReadMe associates this content with an operation by its `operationId`.
3. Add the specification to your Mintlify repository and configure [OpenAPI-generated pages](/docs/api-playground/openapi-setup).
4. Move valuable supplemental Markdown into the relevant operation description, schema description, or an adjacent guide.
5. Compare authentication, server URLs, code samples, examples, and endpoint order with your original reference.

ReadMe can also ingest Swagger 2.0 and Postman Collections. Retrieve the converted or original OpenAPI source before configuring Mintlify rather than copying the rendered reference.

## Migrate your versions

ReadMe versions and branches apply to Guides, Recipes, and API Reference content, while some of your project content remains shared across versions. Inventory each version separately and map maintained versions to Mintlify [version navigation](/docs/organize/navigation#versions).

Check for the following patterns.

* A different default version and URL behavior
* Hidden, beta, and deprecated versions
* Version-specific Reusable Content
* Pages that exist in only one version
* API specifications that differ by version
* Shared Custom Pages or changelog content

## Download images and files

Your ReadMe ZIP export does not contain hosted images. Use the image URLs in your export or the ReadMe API to download the original files, then add them to your Mintlify repository.

Do not rely on remote ReadMe asset URLs for your final site. Copy the files you own, update their references, and verify alt text and downloadable-file links.

## Preserve URLs

Your ReadMe URLs can include the project version and content type, such as `/docs/`, `/reference/`, or `/page/`. Export a sitemap or crawl your published site to capture the actual paths.

Add [redirects](/docs/create/redirects) for every path that changes. Pay special attention to:

* Default-version URLs that omit the version segment
* Custom Pages under `/page`
* Guides and reference pages with the same slug
* Endpoint paths derived from OpenAPI tags and summaries
* Deprecated or hidden pages that still receive traffic

## Review your migration

Compare your ZIP export, API inventory, and published sitemap against your migrated files, then preview every maintained version.

Search your converted files for leftover ReadMe syntax: magic blocks, variables, glossary references, and Custom Block directives.

## Launch your new site

* Set a content freeze on your former site and track every change made to it after your migration snapshot.
* Confirm your production branch and repository on the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page of your dashboard.
* Record your existing DNS records and keep your former site running until you verify your Mintlify deployment is live.
* Review the navbar, footer, favicon, logo, colors, and typography.
* Review site and page metadata, canonical URLs, and indexing preferences. See [SEO and search settings](/docs/organize/settings-seo).
* Install any required [analytics integrations](/docs/integrations/analytics/overview), and optionally add a [custom 404 page](/docs/customize/custom-404-page).
* If you migrated an API reference, compare endpoint pages, navigation structure, server URLs, authentication schemes, and examples with your former site.
* Preview your exact launch commit in a [preview deployment](/docs/deploy/preview-deployments). Check desktop and mobile layouts, pages from every navigation section, search, and your redirects.
* Check the browser console and network tab for any errors on pages that use custom components or scripts.
* Switch your domain with the [custom domain guide](/docs/customize/custom-domain), which covers the zero-downtime cutover for a domain that already serves documentation.
* After launch, monitor for 404 errors, redirect failures, and build failures.

## ReadMe references

* [Exporting data](https://docs.readme.com/main/docs/exporting-data)
* [Documentation structure](https://docs.readme.com/main/docs/documentation-structure)
* [Versioning](https://docs.readme.com/main/docs/versions)
* [OpenAPI support](https://docs.readme.com/main/docs/openapi)
* [Reusable Content](https://docs.readme.com/main/docs/reusable-content)


## Related topics

- [Migration overview](/docs/migration/index.md)
- [Migrate from GitBook](/docs/migration/gitbook.md)
- [skill.md](/docs/ai/skillmd.md)