Migrate from Docusaurus

Move Docusaurus documentation to ReadMe by choosing the import path that fits your repository, converting unsupported MDX, and verifying the result before cutover. You stop maintaining a build pipeline, a search index, and hosting. You gain an API Reference generated from your OpenAPI file with Try It! built in, and content review through Branches and Reviews.

Choose the easiest migration path

Your situation	Recommended path
You want to evaluate a public site quickly	Use the Importer with your documentation URL, Markdown files, or OpenAPI definition.
Your repository is ready for ReadMe's Git-based import	Prepare the supported repository structure and use the Git-based import workflow.
You need a scripted or CI-based migration	Convert a copy of the repository and upload it with `rdme@10`.
You have only a few pages	Create and review them in the ReadMe editor.
You have many pages, custom components, versions, or access rules	Ask about Enterprise migration assistance.

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

What doesn't transfer, and what replaces it

Markdown, MDX, images, files, and OpenAPI definitions move to ReadMe. Custom React components, swizzled theme code, plugins, and build-time behavior need rebuilding:

What doesn't transfer	Rebuild it with
Custom React components and swizzled theme in `src/theme/`	Custom MDX components
Hand-written endpoint pages	An API Reference generated from your OpenAPI file, with Try It!
Your own search implementation	ReadMe's built-in search
Ad hoc pull-request review of docs changes	Branches and Reviews
`docusaurus.config.js` theming	Themes and Appearance settings
Plugin-generated content, including blog posts	Rebuild manually, or move release notes to the ReadMe Changelog
Localized content (i18n)	Plan translations as a separate step; ReadMe handles localization differently

Inventory your Docusaurus site

Copy the repository and keep the original unchanged.
Record public URLs for high-traffic pages and every version you plan to retain.
List pages that import from @theme, @site, or your component directories.
Review src/theme/, src/components/, and docusaurus.config.js for swizzled code, plugins, generated content, and custom search behavior.

Convert content and navigation

Docusaurus	ReadMe
`title`	`title`
`description`	`excerpt`
`tags`	`metadata.keywords`
`draft: true`	`hidden: true`
`image`	`metadata.image`
`slug`	Preserve it when you need a specific ReadMe URL.
`sidebar_label`	Preserve it as the intended page or navigation title.
`sidebar_position`	Map it to the ReadMe navigation order.

Convert Docusaurus admonitions, tabs, details blocks, and other supported content to ReadMe MDX components. Replace imports only after you replace the imported component or rewrite the affected content. Review all custom JSX and component props individually.

Use sidebars.js and the deployed site to reproduce your navigation. For CLI uploads, every new Guide needs title and category.uri; use position and parent.uri for order and hierarchy. For Git-based import, prepare the documented folders and _order.yaml files.

Migrate versions and API Reference

Create a ReadMe version for each Docusaurus version you will continue to publish. Migrate and review one version at a time, and build redirects from the deployed URLs because current and versioned Docusaurus content can have different path patterns.

Upload a validated OpenAPI definition to create API Reference content. Compare generated operations with hand-written endpoint pages, and retain workflows, explanations, and examples that are not represented in the definition as Guides.

Validate and cut over

For a CLI migration, preview uploads before publishing changes:

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

Resolve the reported errors, then run the Guides upload without --dry-run. Configure API authentication before testing Try It!, and integrate the Metrics SDK separately if you need API-log data in the Developer Dashboard.

Under Admin Settings > Error Pages, add redirects as oldurl -> newurl, one per line. Verify that pages render, assets load, navigation and versions match the content you retained, API Reference includes necessary guidance, and redirects cover high-traffic URLs. Keep Docusaurus available until the cutover is complete.

Optional: continue in Git

After migration, connect a new empty repository through Settings > Git Connection to enable bi-directional Git Sync. Use the Git Sync repository structure and keep branch names aligned with the ReadMe versions you synchronize.

After you migrate

Run a Docs Audit to check content quality against your style guide, 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

Can we retain custom React components?

Rebuild the behavior with custom MDX components when it fits the content model. Rework or remove components that depend on the Docusaurus build, theme, plugins, or client-side application state.

Can we keep a pull-request workflow?

Yes. After you complete the migration, Git Sync can keep ReadMe and a connected empty GitHub or GitLab repository synchronized for ongoing edits.

What happens to the Docusaurus blog?

Move release-oriented posts to your ReadMe Changelog when that suits your publishing workflow. Move longer-form posts to your marketing site or another publishing system, and redirect their existing URLs as needed.

We have translations. What happens?

Plan localization as its own project step. ReadMe handles translated content differently than Docusaurus i18n, so a straight file-for-file conversion will not produce the same structure.