Migration Guide Best Practices

📘
We're in the process of rolling out some big changes to your documentation experience. Check out our overview page to get the details, and keep checking our changelog for updates on the rollout!

A wise philosopher once said that "the only constant in life is change". While they probably said that hundreds of years ago, it couldn't be more applicable to the newly revamped documentation experience coming your way!

As detailed in our overview, the new documentation experience contains tons of improvements, including:

A completely redesigned API Reference section, with improved support for the OpenAPI (Swagger) specification
Redesigned and more performant navigation
Drastically improved mobile-friendliness
and much more!

🚀 Enabling the Updates

If you're using an OAS file for your API reference docs and have kept your custom CSS and JavaScript on the lighter side, this transition should be simple. See our FAQ for info on how to preview these changes in your docs.

If you've done lots of customization or are using the manual editor to write your API reference docs, you'll need to make some updates to your content and code before enabling the new design. We have several tools and tips to help make your migration as smooth as possible!

🗂 Migrating Content with Versions

As part of this migration process, you may find yourself needing to adjust your documentation content. This might be because:

You're using the Manual API Editor, and you want to take advantage of the improved support for response schemas, which are only available in the new design (see Best Practices with the Manual API Editor below for more!) 💫
You're using HTML/CSS blocks in your documentation, and you need to make some style tweaks 🎨
You're moving from a continuous scrolling API Reference to one endpoint per page 📝
Other content refinements to make your documentation look even better in the new design 💅

This can be a challenge because you don't want to change your live documentation, but you want to make sure your content is ready when you flip the switch over to the new design. In order to make the transition as seamless as possible, we recommend using our built-in documentation versioning! Here's a suggested approach:

Navigate to the Versions section in your project dashboard 🧭
Fork your main documentation version (let's say it's v1.0) and name it v1.0-new-design (or something along those lines) 📛
Make sure that the "is public?" option next to v1.0-new-design is unselected 🙈
In the left-hand sidebar in the dashboard, select v1.0-new-design from the dropdown selector (next to the project name) ✅
Make any content edits as you see fit. These changes will only be reflected in v1.0-new-design—no need to worry about your content in v1.0! 📝
You can preview any changes you make on <subdomain>.readmepreview.com. Make sure you log into the docs so you can see the content in the hidden version! 👁
Once you're ready to flip the switch, enable the new design in your project settings 🚀
In your Versions settings, set v1.0-new-design as your main version and hide v1.0. 🔀
Do a quick glance over all your documentation to ensure that everything looks as expected 👀
If everything looks good, you can safely delete v1.0 and rename v1.0-new-design to v1.0! 🗑

🔗 Migrating Links to Reference Pages

While most links to your documentation will remain unaffected, there are certain links to the Reference section that might be incorrect as a result of our move to one endpoint per page (which you can read about in our FAQ below or in our overview page.

To ensure that these links are performant and are taking you to the correct page, you can update your links by simply taking the hash parameter value in the legacy link structure and adding it as a path parameter. For example, a link like this (applicable to continuous page structures):

https://docs.readme.com/reference#getproject

should be modified to this:

https://docs.readme.com/reference/getproject

For split reference page structures, links like this:

https://docs.readme.com/reference/project#getproject

should be modified to this:

https://docs.readme.com/reference/getproject

🎨 Migrating Custom CSS and JavaScript

The markup and class names have changed markedly (see what I did there?) in the new designs, so your custom CSS and/or JavaScript will likely require some changes. To make this transition easier, we've created an HTML class that is set on the <html> element (also known as the root element) of every page in the new documentation design: useReactApp. You can check for the existence of this class in your CSS and JS to verify which design is being rendered.

🚧
We strongly recommend duplicating your code and creating separate wrappers for the old and new code to prevent conflicts. And once you've fully migrated over, you can safely delete the old code and remove the wrappers! 🎁

See below for CSS- and JS-specific examples.

Custom Stylesheets

In order to prevent your old CSS from conflicting with any new CSS you write, we recommend prefixing your selectors with html:not(.useReactApp) and/or html.useReactApp to distinguish styles that should be applied to the old and new designs, respectively. See below for examples:

html:not(.useReactApp) #content-body .markdown-body {
	/* Your CSS for the old design goes here */
}

html.useReactApp .rm-Guides .markdown-body {
	/* Your CSS for the new design goes here */
}

The newly-designed docs have lots of different customization options available via CSS variables, which is the recommended approach to customizing your docs. If you're trying to style the Markdown content itself, our Markdown renderer also has several CSS theming options available. You can read about them in our RDMD docs, where you'll also find info on migrating Markdown-specific CSS to the new documentation design.

Custom JavaScript

In order to prevent your old JS from conflicting with any new JS you write, we recommend wrapping your code in if-statements that check for the existence of the .useReactApp class in the root element. See below for examples:

if (!document.documentElement.classList.contains('useReactApp')) {
	// Your JavaScript for the old design goes here
}

if (document.documentElement.classList.contains('useReactApp')) {
	// Your JavaScript for the new design goes here
}

📝 Migrating Your API in the Manual Editor

As mentioned above, an OpenAPI file is the best way to take advantage of all of the new features that the API Reference has to offer. Nevertheless, our manual API editor is an approachable and powerful way to create a great API Reference. While there are many ways to create great docs using the Manual API Editor, we have several recommendations to ensure that your docs will effectively translate into an OpenAPI-friendly format, which will result in a smoother migration and a much more interactive and personalized documentation experience for your users.

We recommend following the versioning steps listed above, and in your newly created version, following our best practices for writing reference docs using the Manual API Editor.

👩‍🏫 FAQ

How can I test or preview these updates?

You can preview the new Reference and design updates by adding your ReadMe subdomain into this url: <yoursubdomain>.readmepreview.com. If you don’t know your subdomain offhand, you can find it in your project settings under Configuration > Custom Domain > ReadMe subdomain.

Do I control when I switch over to the new design, and what's the deadline?

Yes, you’ll be in control of when you migrate! This will be configured by you in your project settings or manually in coordination with us. We’ll be supporting the legacy Reference through the end of 2021 to allow customers plenty of time to make any adjustments you need in your content or CSS.

What happens to my CSS, and how can I update my CSS for the new design?

Since we’re using new class names in the new Reference section, we’d expect customers with a lot of custom CSS to need to make some updates. See above for our best practices on making these updates!

Do I have to switch from continuous scroll to one endpoint per page?

We know it’s an adjustment, but we can share some more context on why we’ve made the new Reference only available with one endpoint per page. We want to ensure every entry point into your docs provides all the information that a developer needs to get started, including authentication. This way developers aren’t needing to jump around in your docs to find header authentication, packages they need to install, API keys, error examples, etc. Everything they need to make a call is right there.

Having each endpoint as a unique page makes that possible — it would really slow down performance to need to load all of that content over and over again as you scroll. Continuous scroll behavior is just accepted as standard (going all the way back to Stripe or Twilio’s original 3 column docs), even if it’s not the best design solution. While we know it’s a change, we’ve actually gotten really positive feedback on this change from other customers after trying it out.

How can I consolidate pages and set up redirects?

If you were previously using continuous scroll, you may end up wanting to consolidate some of these content pages into a single page. If that's the case, you can make those content changes directly in your ReadMe admin dashboard and publish them whenever you are ready. If you deprecate any pages as part of this process, be sure to set up redirect links following these instructions.