Migrate from another platform

Move documentation from another platform to ReadMe by selecting the easiest supported import path, converting source-specific syntax, and verifying content before cutover. Whatever you're moving from, you gain an OpenAPI-generated API Reference with Try It!, reusable content blocks, and structured review through Branches and Reviews.

Choose the easiest migration path

Your situation	Recommended path
You want to evaluate public documentation quickly	Use the Importer with a URL, Markdown files, or an OpenAPI definition.
You have a prepared Markdown or MDX repository	Use Git-based import with the supported repository structure.
You need repeatable bulk uploads or CI automation	Use `rdme@10`.
You have a small content set	Create and review pages in the ReadMe editor.
You have a large, complex, or enterprise migration	Ask about Enterprise migration assistance.

Use bi-directional Git Sync after migration when you need ongoing two-way editing. It connects ReadMe to a new, empty GitHub or GitLab repository and does not import an existing repository.

What commonly doesn't transfer, and what replaces it

What doesn't transfer	Rebuild it with
Custom components or theme-specific markup	Custom MDX components
Platform-specific theming and branding	Themes and Appearance settings
Hand-written endpoint documentation	An API Reference generated from your OpenAPI file, with Try It!
Includes or content snippets	Reusable content
No OpenAPI file yet	Build one with the API Designer
Ad hoc review of documentation changes	Branches and Reviews

Export and inventory source content

Source	Start with
Document360	Export articles, categories, and media.
Redocly	Collect Markdown, the OpenAPI definition, and `redocly.yaml`.
Scalar	Collect the OpenAPI definition and separately maintained Markdown guides.
Slate	Convert the Markdown source and includes into individual Guide pages.
Hugo, Jekyll, or MkDocs	Export Markdown and retain site configuration for navigation and redirects.
Sphinx	Convert reStructuredText to Markdown, then review directives and cross-references.
A custom CMS	Export one Markdown file per page with metadata, assets, and its source URL.

Keep the original export unchanged. Inventory page metadata, navigation, reusable content, images, downloads, OpenAPI files, custom markup, access rules, and public URLs before conversion.

Convert content and navigation

Convert one representative page for each source-specific construct, verify the result, and then automate only the conversions you have tested. Resolve build-time variables before upload, replace includes with reusable or inline content, and rebuild custom components only when they fit the ReadMe MDX model.

For CLI uploads, every new Guide needs title and category.uri; use position and parent.uri to define navigation. For Git-based import, prepare the supported folders and _order.yaml files.

---
title: Install the SDK
category:
  uri: Getting Started
position: 2
---

Upload and validate

Validate and upload an OpenAPI definition when you have one, then preview Guides before publishing:

npx rdme@10 openapi validate ./openapi.yaml
npx rdme@10 openapi upload ./openapi.yaml --key="$README_API_KEY"
npx rdme@10 docs upload ./docs --key="$README_API_KEY" --dry-run

An OpenAPI upload creates API Reference content from the operations in the definition. Compare it with hand-written endpoint content before removing that content, and retain workflows and conceptual guidance that the definition does not contain. Configure authentication before testing Try It!, and integrate the Metrics SDK separately when you need API-log data in the Developer Dashboard.

Set up redirects and cut over

Create redirects from the source sitemap, navigation, and traffic data. Under Admin Settings > Error Pages, add each redirect as oldurl -> newurl. Verify source-specific markup is gone, assets load, navigation and access settings are correct, API Reference has the necessary supporting content, and redirects cover high-traffic URLs.

Keep the existing site available until you verify the migration and complete domain cutover.

Optional: continue in Git

After migration, connect a new empty repository through Settings > Git Connection for bi-directional Git Sync. Use folders and _order.yaml files to manage navigation in that ongoing workflow.

After you migrate

Run a Docs Audit to check content quality, build guided walkthroughs with Recipes, and use My Developers to see how developers use your API once your Metrics integration is live.

Frequently asked questions

We do not have a Markdown export. What should we do?

Use the platform API or an export tool to create one Markdown file per page. Include the title, source URL, parent page, ordering data, assets, and visibility state so you can reproduce the published site accurately.

We're on Sphinx and our cross-references are everywhere.

Convert with a tool such as Pandoc, then handle cross-references as a second pass. They usually become plain relative links, and a script can resolve most of them from the reference labels.

Do we need to migrate everything at once?

No. You can publish API Reference content from a validated OpenAPI definition separately from your Guides. Keep the existing documentation available until you have reviewed both areas and prepared redirects.