Customer StoriesReadMe Blog
Guides
Start typing to search…

ReadMe Refactored: Overview and Migration Guide

Overview

We're excited to introduce our a 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.

ReadMe’s New UI
Create and edit your docs with a new design that brings your content and appearance changes closer to what your users see.
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.

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!

Feature

Refactored

Additional information

Bi-directional Github sync

✅

rdme@10

✅

Requires upgrade from rdme@9 and earlier

Direct In-docs editing

✅

Now a MDX-powered editor

MDX Components

✅

Reusable Content

✅

APIv2

✅

Requires upgrade from APIv1

OpenAPI/Swagger

✅

API Designer (Manual API definition)

✅

Array of Objectssupport coming soon!
$refsare not supported
Reusable object definitions not supported in API Designer

GraphQL

✅

Owlbot AI

✅

Branching

🛠️

Coming soon!

Suggested Edits

❌

Currently unavailable

AWS Gateway Integration

❌

Currently unavailable

Export Markdown

❌

Coming soon!

Alternative: Use bi-directional sync to import/export content

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.

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.

  • objectOfArrays
  • AWS Gateway Plugin

If you're not using the features mentioned above, you may be eligible for immediate migration! To kick off the process, click on the "Get New Experience" button from your project's Home page and follow the instructions on the following 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 Users

🚧

Important Note for Enterprise Customers

The new ReadMe experience will be rolling out to Enterprise customers in mid-2025. This includes features like bi-directional Git syncing, MDX components, branching and the new editing interface. For more details about the Enterprise rollout timeline or to discuss your specific migration needs, please contact your Customer Success Manager.

New and Improved Features

You'll have access to all standard features mentioned above plus:

  • Branching including a review and approval process, an upgrade to Staging! (Coming soon)
  • Enhanced team collaboration tools
  • Comprehensive audit logging
  • Enterprise-grade security features

Enterprise Migration

For all Enterprise customers, your CSM will reach out with more details on the timeline for upgrading your Enterprise group and corresponding child project to ReadMe Refactored. In the meantime, please reach out to your CSM if you'd like to discuss any of the following:

  • Detailed information about Enterprise-only features in Refactored
  • Scheduling a migration planning session for your organization
  • Personalized training sessions on new features coming to ReadMe Enterprise

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 6 days ago