How can I add a custom domain to a docs site?
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
For a full guide on setting up domains and information visit our documentation.
Here are some examples of domains you can set in GitBook.
Apex domain
example.com
❌
www subdomain
www.example.com
✅
Custom subdomain
docs.example.com
help.example.com
anything.example.com
✅
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.io
Please use the value displayed in the GitBook app and not the value in the screenshot above.
Configuring DNS happens outside of GitBook, at the DNS provider you are using for your domain.
There are three parts to this step:
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.
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.
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:
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.
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.
Once your CNAME record is successfully added within your DNS settings through your DNS provider, you can continue the domain connection process in GitBook.
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.
