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'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 `
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 `
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 `
## 🔗 Migrating Links to Reference Pages
While most links to your documentation will remain unaffected, there are certain links to the <<glossary: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):
should be modified to this:
For split reference page structures, links like this:
should be modified to this:
<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:
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.
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:
## 📝 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](🔗).