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.

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.

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.

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:

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.

ReadMe's file structure generally separates content by type.

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.

See Navigation for more information on how to structure navigation elements.

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

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. Your export might expand a reusable block into each page, so compare the copies and consolidate only identical 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.
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.

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.

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

Your ReadMe ZIP export does not contain hosted images. The exported Markdown references them by their original hosted URL (typically on files.readme.io). Download those files and commit them to your Mintlify repository before you go live.

To download every referenced asset from an export:

1. From the root of your unzipped export, extract asset URLs from the Markdown:

   grep -rhoE 'https://files\.readme\.io/[^)"\s]+' . | sort -u > asset-urls.txt

2. Download each file into an images/ directory in your Mintlify repository:

   mkdir -p images && cd images && wget -i ../asset-urls.txt

3. Update the Markdown references to point to the new local paths (for example, replace https://files.readme.io/abc123-diagram.png with /images/abc123-diagram.png).

For images or files that are not linked from the export (for example, assets attached only to Custom Pages or referenced from JSON magic blocks), use the ReadMe API to enumerate and download them.

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.

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 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

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.

• 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 page of your dashboard.
• Record your existing DNS records and keep your former site running until you verify your Mintlify site 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.
• Install any required analytics integrations, and optionally add a 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. 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, which covers the zero-downtime cutover for a domain that already serves documentation.
• After launch, monitor for 404 errors, redirect failures, and build failures.

• Exporting data
• Documentation structure
• Versioning
• OpenAPI support
• Reusable Content

• Migrate docs into Mintlify from a ZIP export
• Migration overview
• Migrate from GitBook