How can I add a custom domain to a docs site?

To add a custom domain to your docs site:

Navigate to the "Docs Sites" section in the left-hand panel under the Home tab.
Select the specific site where you want to add a custom domain by clicking on it.
Above the list of spaces, locate the "settings" option and click on it. This action will direct you to the settings page for your docs site. You'll see an option for "Setup Custom Domain". Click this to begin adding a custom domain to your docs site.

Keep in mind that the length and structure of your URLs will vary depending on whether your custom domain is configured at the organization or site level. Read our guide on deciding where to set the domain here.

For a full guide on setting up domains and information visit our documentation.

1. Choose a subdomain and its location

Here are some examples of domains you can set in GitBook.

Domain type

Example

Supported?

Apex domain

example.com

❌

www subdomain

www.example.com

✅

Custom subdomain

docs.example.com

help.example.com anything.example.com

✅

Decide where to set the custom domain

There are two levels at which a custom domain can be set:

At the organization level
At the docs site level

Your URL path will depend on where you set the domain.

Organization custom domains

Because organizations can contain many sites (and internal spaces) any custom domain set for the organization will apply to all published sites unless overridden.

Each published site will follow after your organization's domain

Org-domain/site-name/page-group/page

If you’ve decided that you want to set a custom domain at the organization level, you can go to the next step for details on how to set it. If you’re not sure, keep reading to review your other options.

Site custom domains

If you want to set up a domain different from your main organization domain, or you want to maintain a shorter URL path, you should set the domain directly at a site level.

For example, the domains set for Site A and Site B could be:

site-a-domain/page-group/page
site-b-domain/page-group/page

Domains set at a site level will have the following path

If no page groups are used: site-domain/page

(Or, if page groups are used:site-domain/page-group/page)

2. Initiate the custom domain set-up

Custom domain set-up steps for organizations and sites are similar but will impact your future published URL path. This is why it's important that you decide where to set the domain and follow the correct guide below.

Guide for organization domains

You’ll find the options for setting a custom domain for an organization within the organization settings page. Open the Settings menu in the lower left corner, and click on Organization Settings.

In the General section, scroll to the Publishing section and under Custom Domain, click Connect a domain
This will open a window where you can enter the custom domain, then click Next: Configure DNS
The final step requires you to copy the name and value to your clipboard so that you can create a CNAME DNS record. To copy the information click on the icon on the right-hand side of each field. Once copied, you can move on to configuring the DNS.

The value for the CNAME record will be in the format: [example]-hosting.gitbook.ioPlease use the value displayed in the GitBook app and not the value in the screenshot above.

Guide for site domains

The method for configuring a site domain typically mirrors the approach for setting up an organization domain. The primary distinction lies in step 1 which is the initial location for initiating the custom domain configuration.

Navigate to the site for which you want to set the custom domain. Click Settings then choose Set up a custom domain

This will open a window where you can enter the custom domain, then click Next: Configure DNS

The final step requires you to copy the name and value to your clipboard so that you can create a CNAME DNS record. To copy the information click on the icon on the right-hand side of each field. Once copied, you can move on to configuring the DNS.

The value for the CNAME record will be in the format: [example]-hosting.gitbook.ioPlease use the value displayed in the GitBook app and not the value in the screenshot above.

3. Configure the DNS

Configuring DNS happens outside of GitBook, at the DNS provider you are using for your domain.

There are three parts to this step:

Configure a CNAME record

The names of the fields and what to enter to configure the record may differ between DNS control panels, but we’ve covered the most common options here. If you’re in any doubt, check with your DNS provider.

The type is the kind of DNS record that you want to create. Here, you need to choose CNAME.
The name or DNS entry is where you enter your subdomain. You might need to enter it in full (e.g. docs.example.com) or you might need to enter the part before your apex domain (e.g. docs). If you’re unsure which to use, check with your DNS provider.
The target, value or destination is where the subdomain should be pointed.

You might also see a field named TTL, which stands for Time To Live. It’s the number of seconds that the DNS record can be cached for.

To determine an appropriate TTL (Time to Live) for your new DNS records, you can reference the TTL values of your existing records. Matching these values is a safe practice if you're unsure of what to set for the new ones. Alternatively, we suggest setting 43200 seconds (12 hours) or 86400 seconds (24 hours).

Here’s an example of how a correct configuration looks in Cloudflare’s control panel:

Note: a CNAME record cannot co-exist with another record for the same name. If you already have an A record, AAAA record, TXT record, or any other type of record for your chosen subdomain, you would need to remove those, before adding the CNAME record.

Are you using Cloudflare?

If you are configuring DNS in Cloudflare’s control panel, please ensure that Cloudflare’s proxying (the orange cloud, also called "Proxy status" in your domain settings) is disabled.

This is for two reasons:

This option obfuscates the DNS target for your domain to the public, preventing GitBook from properly running routine checks on your custom domain.
Your custom domain will already benefit from Cloudflare’s CDN and a Google Trust Services SSL certificate on our end.

Again, please turn off Cloudflare proxying to ensure that your documentation is served without issues and can be monitored by GitBook.

GitBook does not officially support proxy setups

If you decide to set it up anyway, please ensure your setup respects the following:

You need to proxy all GET, OPTIONS, HEAD, POST methods.
You should respect the Cache-Control header and use the entire request (URL + headers, by respecting the Vary header) as a cache key.
You should not modify the HTML to load external resources, or you should consider the CSP and ensure a nonce is set on every resource.

Check for a CAA record

CAA records enable you to specify who can issue an SSL certificate for the domains you own. We use Google Trust Services to issue an SSL certificate for your custom domain, so this needs to be allowed. There are two ways to do this:

Have no CAA record. Without a CAA record, there are no limitations on which SSL providers can issue an SSL certificate for your domain.
Have a CAA record that explicitly allows Google Trust Services. If a CAA record exists, any providers not explicitly allowed will be blocked. The following is the value that would need to be included in a CAA record to allow Google Trust Services:

0 issue "pki.goog"

Wait for the changes to take effect

DNS records are cached for a defined period, known as the Time to Live (TTL). This caching is beneficial for performance since DNS records rarely change.

The Time to Live (TTL) value specifies when DNS cache servers must refresh their cache by checking for updates, ensuring they respond with the most current information.

In most cases, it’s best to allow at least an hour before moving to the final step of custom domain set-up.

You might need to wait 1-48 hours for the DNS changes to take effect.

Want to check how this process, known as propagation, is progressing?

You could use a DNS lookup tool, such as WhatsMyDNS.

Enter your full subdomain, select CNAME from the dropdown list, and press the Search button. DNS cache servers around the world will respond to let you know what their cached result is. You’ll want to periodically check these results until the majority respond with your assigned CNAME value.

Once DNS propagation has been completed, you can move on to the last step: confirming the custom domain setup.

4. Finalize the custom domain setup

Once your CNAME record is successfully added within your DNS settings through your DNS provider, you can continue the domain connection process in GitBook.

Finalize the domain setup

After completing the second and third steps, the Configure your DNS screen should let you advance by clicking Ready: Go Live. This starts GitBook’s validation process.

During this phase, GitBook verifies your CNAME record and configures the SSL certificate for your domain, ensuring a secure connection.

When this process is finished, a success notification confirms that your site is live. Although this process generally proceeds without issues, occasional errors can occur.

Should you encounter any challenges, make a note of the error and refer to our troubleshooting guide. If troubleshooting doesn’t work or the issue isn’t addressed in our guide, don't hesitate to contact our support team for assistance.

Last updated 9 days ago