Upgrade to Enterprise

An Enterprise Group ties multiple doc projects together under a single custom domain. Each project keeps its own Guides and Reference sections, so a group works well when you need manage multiple products at scale.

Upgrading to an Enterprise Group unlocks features such as:

• Global search across every project.
• A global landing page with shared CSS and JS.
• OAuth 2 login for customers and SSO login for employees.
• Audit logs to track changes.

Before You Start

Plan these items before you begin the upgrade process:

• Custom domain - Decide whether to keep your current domain or move to a new global domain such as developers.mypets.com.
• ReadMe subdomains - Your project's ReadMe subdomain becomes visible in your URLs after migration. See How Your URLs Change​.
• Redirects - Author Your Redirects in Advance in a text editor to ensure smooth transition into your Enterprise Group.

Migrate Your Projects

Work through these steps in order. ReadMe creates the group and reserves any new subdomains for you. You can request a test group to rehearse the move before you go live. Everything else you can do from the Enterprise Group dashboard.

1. Remove the custom domain from your current project.

2. Once your enterprise group exists, add your custom domain to the group's dashboard.

3. Add your redirects. After you have access to the group project, paste the redirects you drafted into the group's dash. If you changed your custom domain, add your 301 redirects to your own web server as well.

4. Add your doc projects at dash.readme.io/group/yourGroup/settings so they appear as links on your global landing page.

5. Move your integrations to dash.readme.io/group/yourGroup/integrations. If multiple projects each have integrations, pick one project's settings to apply across the group.

6. Set up Custom OAuth at the group level instead of the project level.

7. Choose how readers land on your docs: use the global landing page, or redirect past it to a child project or your own landing page.

8. Review navigation between projects at dash.readme.io/project/yourProject/v2.0/usability, and consider adding links in the project header.

9. Click Publish to launch your docs.

How Your URLs Change

When an existing project joins a group, its URLs gain the project's ReadMe subdomain as a path segment:

projectCustomDomain.com/docType → groupCustomDomain.com/projectSubdomain/docType

Your ReadMe subdomain was hidden behind your custom domain before, but it becomes visible in the URL path once you're in a group. Rename it before migration so it reads well in public URLs.

URL Change Example

Consider the company myPets, which has one cats project at docs.mypets.com and administers it at dash.readme.io/project/project1pets. Left unchanged, that project would land at developers.mypets.com/project1pets after the upgrade.

To fix this, rename the ReadMe subdomain to cats before upgrading, so you administer it at dash.readme.io/project/cats. Add new projects with subdomains like dogs, birds, and other-animals. After the upgrade your projects resolve to developers.mypets.com/cats, developers.mypets.com/dogs, and so on. Renaming the subdomain doesn't affect readers, who still reach you through your custom domain.

For more detail, see URL Paths in ReadMe.

Author Your Redirects in Advance

Draft your redirects before the migration so you can paste them in as soon as your group is ready. Where you add them depends on what you change. Here's how the scenarios look for the myPets example above:

Custom Domain Changes

When your custom domain changes from docs.mypets.com to developers.mypets.com, author a 301 redirect for each doc type on your own web server. These push traffic from your old domain to your new one and can't live in the group dash.

Subdomain Redirects

If you keep your original custom domain instead of changing it, you handle every redirect in the group dash. Your subdomain becomes visible, so docs.mypets.com/docs becomes docs.mypets.com/cats/docs.

In your group project at dash.readme.io/group/myPets-parent/errorpages, author a redirect for each doc type using these patterns:

/docType/(\S*) -> /childSubdomain/docType/$1
/docType -> /childSubdomain/docType

For a cats project with docs and API reference enabled:

/docs/(\S*) -> /cats/docs/$1
/docs -> /cats/docs
/reference/(\S*) -> /cats/reference/$1
/reference -> /cats/reference

These patterns catch both deep links like docs.mypets.com/docs/cat-habits and the top-level landing page at docs.mypets.com/docs. The (\S*) and $1 are regular expressions, so one line covers every page under a doc type instead of one redirect per page.

Existing Page Redirects

Copy any per-page redirects from dash.readme.io/project/cats/errorpages into your group at dash.readme.io/group/myPets-parent/errorpages, and prefix each with the project subdomain. For example:

docs/care-and-feeding-of-cats -> docs/cat-care

becomes:

cats/docs/care-and-feeding-of-cats -> cats/docs/cat-care

For more on redirect formats, see Redirect Scenarios and Error Pages.