ReadMe Refactored: Overview and Migration Guide
We're excited to introduce our new editing experience that brings powerful features including bi-directional Git syncing, MDX support, and a streamlined editing interface. This guide explains what's new, how to migrate your project on your own, and the migration process for Enterprise customers.
What's New
We've refactored every part of ReadMe to support the next generation of APIs, making it easier for people with all levels of technical skills to contribute. Check out the new features and don't miss the full feature list further down—we're just getting started.
See It In Action
Watch the video to get a firsthand look at how the new features work and feel!
Feature Compatibility
We're continuing to release new features for Refactored as we work toward full feature parity, and keep this table updated to notify you of all new updates and improvements. If a feature that you use isn't currently available on the Refactored experience, rest assured that it'll be available soon!
Legacy | Refactored | Additional information | |
---|---|---|---|
Layout Themes NEW | |||
Github syncing NEW | |||
Branching NEW | |||
Suggested Edits | Not available1 | ||
MDX Components NEW | |||
rdme@10 NEW | |||
API Designer |
| ||
APIv2 NEW | |||
GraphQL | |||
AWS Gateway Integration | Not available1 | ||
Localize Integration | This may require an update to your translations after migrating |
Features are actively being worked on and will be available in the new ReadMe UI soon.
Alternative Solutions
If you're currently using features that aren't supported in the new experience, our support team can help you transition to supported alternatives. Please reach out to our support team for assistance in planning your migration strategy.
Enterprise Features
To view features specific to the Enterprise plan or if you‘re ready to migrate your group, continue to “Enterprise Customers” to read more about the migration process.
Migrating On Your Own
If you're currently using any features listed below, your project is not quite ready to migrate. While we're working to build these feature, you can join our waitlist from the migration page accessible through your project's home page.
- AWS Gateway Plugin
- Suggested Edits
If you're not using the features mentioned above, you may be eligible for immediate migration! To kick off the process, click on "Migrate to the New Experience" and "Get Started" buttons from your project's Home page and follow the instructions on the next screens.

ReadMe Refactored migration banner
⚠️ Before You Migrate
A few things to prepare for:
- Most projects migrate in around 10 minutes, but the process may take up to 2 hours depending on the size of your project.
- Your project dashboard will be temporarily disabled, but your docs will remain live and accessible during the entire process.
- This update contains breaking changes to our CLI (rdme) and API.
- Suggested Edits is not supported on Refactored. You will lose access to viewing and merging any existing Suggested Edits.
- We are migrating your content from Markdown to MDX which may cause the localization integration to treat the content as new, which will require re-translation.
- This is a non-reversible process. Once you migrate to the new editing experience, you cannot revert to the previous version.
- Your entire project is being migrated to a Git-backed system.
- You can contact [email protected] if you have any questions.
Enterprise Customers
Legacy | Refactored | Additional information | |
---|---|---|---|
Global Reusable Content | |||
Global Custom Components NEW | |||
Staging | Check out our new Branching feature instead | ||
Branching: Reviews NEW | Coming soon! | ||
Translations | Not available1 |
Features are actively being worked on and will be available in the new ReadMe UI soon.
Migration Process
Important: Please review the “Feature Compatibility” and “Before You Migrate” sections above, as some features may be unavailable or require an upgrade to APIv2 and
readme@10
.
To ensure a smooth transition for all customers, we're gradually rolling out the new experience to enterprise customers. If you don't see the banner yet, your organization may not have access at this time. If the banner is visible, follow these steps to begin the migration process:
- Check your eligibility in your Group Dashboard in the migration banner.
- If you’re eligible, you’ll be prompted to Schedule a Date to migrate your docs that works best for your team. If a call is required, it’s to ensure any necessary updates or changes to your workflow are addressed to ensure migration goes smoothly.
- We will confirm the migration schedule with you before initiating any changes. You'll receive an estimated timeline along with all the necessary details for migrating your group and its child projects.
- After the confirmed time is set, we will go ahead and migrate your group. During this time, you will be locked from your dashboard so changes do not occur during the migration.
- Once the migration is complete, we’ll send a follow-up email once your group has been successfully migrated!

Enterprise migration banner
Need Help?
If you encounter any issues during or after migration:
- Review our Migration FAQ
- Contact support through your dashboard
- Enterprise customers: Reach out to your CSM
Updated 13 days ago