Custom Domains and White Labeling

Once a project is imported into Read the Docs, by default it’s hosted under a subdomain on one of our domains. If you need a custom domain, see Custom domain support.

Subdomain support

Every project has a subdomain that is available to serve its documentation. If you go to <slug>, it should show you the latest version of your documentation. A good example is For Read the Docs for Business the subdomain looks like <slug>

Custom domain support

You can also host your documentation from your own domain.


We don’t currently support pointing subdomains or root domains to a project using A records. DNS A records require a static IP address and our IPs may change without notice.

In order to setup your custom domain, follow these steps:

  1. For a subdomain like, add a CNAME record in your DNS that points the domain to For a root domain like use an ANAME or ALIAS record pointing to

  2. Go the Admin tab of your project

  3. Click on Domains

  4. Enter your domain and click on Add

By default, we provide a validated SSL certificate for the domain. This service is generously provided by Cloudflare. The SSL certificate issuance can take about one hour, you can see the status of the certificate on the domain page in your project.

As an example, fabric’s DNS record looks like this:

dig CNAME +short

Strict Transport Security

By default, we do not return a Strict Transport Security header (HSTS) for user custom domains. This is a conscious decision as it can be misconfigured in a not easily reversible way. For both Read the Docs Community and Read the Docs for Business, HSTS for custom domains can be set upon request.

We always return the HSTS header with a max-age of at least one year for our own domains including *, *, and

Multiple documentation sites as sub-folders of a domain

You may host multiple documentation repositories as sub-folders of a single domain. For example, and This is a way to boost the SEO of your website.

See Subprojects for more information.


SSL certificate issue delays

The status of your domain validation and certificate can always be seen on the details page for your domain under Admin > Domains > YOURDOMAIN.TLD (details).

  • For Read the Docs Community, domains are usually validated and a certificate issued within minutes. However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes and then update DNS hours or days later, this can cause a delay in validating because there is an exponential back-off in validation. Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation.

  • For Read the Docs for Business, domains can take up to a couple days to validate and issue a certificate. To avoid any downtime in moving a domain from somewhere else to Read the Docs, it is possible to validate the domain and provision the certificate before pointing your domain to Read the Docs.

Certificate authority authorization

Certificate authority authorization (CAA) is a security feature that allows domain owners to limit which certificate authorities (CAs) can issue certificates for a domain. This is done by setting CAA DNS records for your domain. CAA records are typically on the root domain, not subdomains since you can’t have a CNAME and CAA record for the same subdomain. Here’s an example for

dig CAA +short
 issue ""
 issue ""
 issue ""

If there are CAA records for your domain that do not allow the certificate authorities that Read the Docs uses, you may see an error message like pending_validation: caa_error: YOURDOMAIN.TLD in the Read the Docs dashboard for your domain. You will need to update your CAA records to allow us to issue the certificate.

  • For Read the Docs Community, we use Cloudflare which uses Digicert as a CA. See the Cloudflare CAA FAQ for details.

  • For Read the Docs for Business, we use AWS Certificate Manager as a CA. See the Amazon CAA guide for details.


If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website) to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs, else it will always redirect to GitBook.

Canonical URLs

Canonical URLs allow people to have consistent page URLs for domains. This is mainly useful for search engines, so that they can send people to the correct page.

Read the Docs uses these in two ways:

  • We point all versions of your docs at default version, usually “latest” or “stable”, as canonical.

  • We point at the user specified canonical URL, generally a custom domain for your docs.


Fabric hosts their docs on Read the Docs. They mostly use their own domain for them This means that Google will index both and for their documentation.

Fabric will want to set as their canonical URL. This means that when Google indexes, it will know that it should really point at


You can set the canonical URL for your project in the Project Admin page. Check your Admin > Domains page for the domains that we know about.


If you are using Sphinx, Read the Docs will set the value of the html_baseurl setting (if isn’t already set) to your canonical domain.

If you are using MkDocs, you can use the site_url setting.

If you look at the source code for documentation built after you set your canonical URL, you should see a bit of HTML like this:

<link rel="canonical" href="" />