ReadMe Refactored Upgrade 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 upgrade your project on your own, and the upgrade 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.

MDX Support

Enhance your docs with interactive components by combining the simplicity of Markdown with the power of JSX.

Bi-Directional Git Sync

Write documentation wherever works best for you, seamlessly syncing between ReadMe and your Git repositories.

Branches

Make changes and review them in a preview environment before publishing.

AI Features

Whether your team wants help editing your docs or your end devs want to get to know your API better, it's all possible with our new AI Features—AI Agent, MCP Servers, Ask AI, and LLMs.txt.

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!

	Refactored	Additional information
Layout Themes NEW
Github syncing NEW
Branching NEW
Suggest Edits in GitHub		Requires GitHub syncing to a public repository
MDX Components NEW
Reusable Content
rdme@10 NEW		Requires upgrade from rdme@9 and earlier
API Designer (Manual API Definition)		`$refs` and reusable object definitions are not supported
API v2 NEW		Requires upgrade from API v1
OpenAPI/Swagger
GraphQL
LLMs & Ask AI NEW
Owlbot AI
AWS Gateway Integration	Not available¹
Localize Integration		This may require an update to your translations after upgrading

¹ These features are not yet on the new ReadMe UI. Customers who rely on any of these functionalities should not upgrade.
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 upgrade strategy.

Enterprise Features

To view features specific to the Enterprise plan or if you‘re ready to upgrade your group, continue to “Enterprise Customers” below to read more.

Upgrading On Your Own

If you're currently using any features listed below, your project is not quite ready to upgrade. While we're working to build these feature, you can join our waitlist from the upgrade 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 upgrade! To kick off the process, click on "Upgrade to the New Experience" and "Get Started" buttons from your project's Home page and follow the instructions on the next screens.

⚠️ Before You Upgrade

A few things to prepare for:

Most projects upgrade 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 upgrading 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 upgrade to the new editing experience, you cannot revert to the previous version.
Your entire project is being upgraded to a Git-backed system.
You can contact [email protected] if you have any questions.

Enterprise Customers

	Refactored	Additional information
Global Reusable Content
Global Custom Components NEW
Editor Role NEW
Branching: Reviews NEW		Review and compare your branch to production before merging
GitHub Enterprise Server (GHES) NEW
Staging		Check out our new Branching feature instead
Translations	Not available¹

¹ These features are not yet on the new ReadMe UI. Customers who rely on any of the legacy functionalities should not upgrade.
Features are actively being worked on and will be available in the new ReadMe UI soon.

Upgrade Process

🚧
Important Please review the “Feature Compatibility” and “Before You Upgrade” sections above, as some features may be unavailable or require an upgrade to APIv2 and rdme@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 upgrade process:

Check your eligibility in your Group Dashboard in the upgrade banner.
If you’re eligible, you’ll be prompted to Schedule a Date to upgrade 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 upgrade goes smoothly.
We will confirm the upgrade schedule with you before initiating any changes. You'll receive an estimated timeline along with all the necessary details for upgrading your Enterprise Group and its child projects.
After the confirmed time is set, we will go ahead and upgrade your Enterprise Group. During this time, you will be locked from your dashboard so changes do not occur during the upgrade, however your public docs site will remain entirely live and accessible to your customers.
Once the upgrade is complete, we’ll send a follow-up email once your Group has been successfully upgraded!

Need Help?

If you encounter any issues during or after upgrade:

Review our Refactored Upgrade FAQ
Contact support through your dashboard
Enterprise customers: Reach out to your CSM