Combine multiple existing sites into one using site sections

We run through the process of centralizing all your existing documentation in a single site using site sections in GitBook

With site sections, you can now publish multiple spaces under one docs site — featuring global search. If you already have multiple sites published separately, or you’re using variants to publish different spaces, combining them into a single docs site will give your readers a much better experience.

Below, we’ll explain the best process for building your new, centralized docs site.

You’ll need to be on one of our new pricing plans to use site sections. Please reach out to our support team if you’re interested in migrating.

Create a new Ultimate docs site

To make the transition from your existing sites smooth, it’s a good idea to create a new sandbox site where you can set up your new structure.

To do this, Click the + next to the Docs sites header in the sidebar to create a new site. For now, give it a name that’s clear that this is a WIP environment, such as “Test – Docs sections”.

Set up your new site structure

In your new docs site’s dashboard, click the Settings tab at the top, then choose the Structure section.

Here, you can organize your new site and add all the content you want. Click Add section to create a new site section and select your the existing space you want.

If you want to add variants — if you have localized your docs into other languages, for example — you can do that for each individual section.

Head to our docs to find out more about structuring your documentation.

You can link a space as many sites as you like — the content of the space will be unaffected. So adding your published spaces here will have no impact on your other live sites.

Match the section slugs to existing site slugs

Once you have your site structure in place, you'll want to ensure that the section slugs match the existing site slugs that you have published today.

You can edit the slugs in the section modal.

Publish with a test domain

Once you’re happy with your site structure, the next step is to understand the impact to your existing site URLs.

To do this, we first need to set up a new custom domain that is different from the existing domain shared by your other sites. For example, if the URL being used by your current sites is docs.company.com you could use docs-test.company.com .

Once you have the test domain set up, hit Publish to push your site live.

Check URL mapping and add redirects where needed

Explore your new site a little and compare the URLs for each site section and variant to the URLs for your existing published sites with that same content.

If some important URLs will change in your new site, you can add redirects in your new site’s Settings page so they point users and search engines to the correct content. For example, if your existing docs landing page is docs.gitbook.com/home, you can set up a redirect from /home to the new landing page of your site.

When you complete your migration and change the domain of your new site to take over the old site’s custom domain, these redirects will automatically send users to the page they need.

Customize the site to mimic your existing docs

Once you’ve set up your site’s structure and redirects, you can customize your site to give it the same look and feel to the existing published content.

If your existing sites use header links or links in your table of contents to link to your other content, these links will no longer be necessary with site sections. You may want to remove the TOC links in each space.

Switch your custom domain to the new site

When you’re happy with all of the customization and structure, it’s time to go live.

If your custom domain is currently being shared by multiple sites, you’ll first need to remove the domain from your organization. Click Settings at the bottom of the GitBook sidebar and choose Organization settings, and remove it in the Publishing section. You can then set it up on the test site that you've been building. Since this will impact your live documentation, you'll want to do this quickly to minimize any downtime. Here is the breakdown of the steps:

Go to organization settings.
Remove the organization-level domain in the Publishing section.
Click Back to the app in the bottom-left corner and return to your docs site’s dashboard.
Open the site’s Settings page and select the Domain and redirects tab.
Configure the domain on the new site by updating the CNAME target value in your DNS provider.

Check your new site is working properly

That’s it! Your new site will be live on your custom domain, and you can explore it to make sure that everything looks right, works as expected, and that the redirects are all correct.

Last updated 1 month ago

Was this helpful?