Setting Up and Verifying a Custom Domain on ReadTheDocs

Problem

When you publish documentation on ReadTheDocs, the default URL looks like https://your‑project.readthedocs.io. For branding or compliance reasons you often want the docs to be reachable via a custom domain such as https://docs.example.com. Setting this up requires several coordinated steps across ReadTheDocs, your DNS provider, and your Sphinx configuration. If any step is missed, the custom domain may resolve to an error page or serve the default ReadTheDocs URL.

Desired Outcome

After completing the guide, https://docs.example.com should:

• Resolve to the correct ReadTheDocs instance.
• Serve a valid SSL certificate issued by Let’s Encrypt.
• Render all relative links correctly thanks to html_baseurl in conf.py.
• Redirect HTTP traffic to HTTPS if “Force HTTPS” is enabled.

Prerequisites

• A ReadTheDocs account with a project that is either public or has the Custom Domains feature enabled (available on paid plans or via the free‑tier toggle).
• Administrative access to the project’s dashboard (Admin > Custom Domains).
• Control over the DNS zone for the target domain (e.g., example.com).
• Knowledge of your DNS provider’s interface for adding CNAME, A, and TXT records.
• A local copy of the project’s conf.py for editing html_baseurl.

Procedure

1. Confirm Plan & Feature
   • Navigate to your project’s dashboard on ReadTheDocs.
   • Under Admin > Custom Domains, verify that the feature is available. If you see an error, upgrade to a paid plan or enable the feature via the free‑tier settings.
2. Choose Your Custom Domain
   • Decide on a subdomain (e.g., docs.example.com) or an apex domain (e.g., example.com). For apex domains you’ll need an A record; for subdomains use a CNAME.
3. Configure DNS
   • For a subdomain (recommended):

     # CNAME record
     docs.example.com.  IN  CNAME  docs.readthedocs.io.
     

   • For an apex domain: add two A records pointing to the IPs provided by ReadTheDocs.

     # A record for apex domain
     example.com.  IN  A  198.185.159.144
     example.com.  IN  A  198.185.159.145
     

   • Set a low TTL (e.g., 300 seconds) to speed up propagation during testing.
4. Add the Domain in ReadTheDocs
   • In the project dashboard, go to Admin > Custom Domains and click Add Custom Domain.
   • Enter the domain you just configured (e.g., docs.example.com) and save.
   • ReadTheDocs will display a TXT record that you must add to your DNS zone for ownership verification.
   • Example TXT record:

     docs.example.com.  IN  TXT  "rdt-verify-unique‑token"
     

   • After adding the TXT record, click Verify Ownership in the dashboard. The status will change to Verified once propagation is detected.
5. Enable Force HTTPS
   • Toggle Force HTTPS on the Custom Domains page. This redirects HTTP traffic to HTTPS once the SSL certificate is available.
   • Do not enable this toggle before the certificate is issued; you may see a 502 error until the cert is provisioned.
6. Update Sphinx Configuration
   • Edit conf.py in your project’s source tree.

     html_baseurl = 'https://docs.example.com/'
     

   • Commit and push the change to trigger a rebuild. The base URL ensures that relative links (e.g., ../index.html) resolve correctly under the custom domain.
7. Wait for SSL Certificate
   • ReadTheDocs automatically requests a Let’s Encrypt certificate once the domain is verified and Force HTTPS is enabled.
   • Check the status in the Custom Domains dashboard; it will display Certificate: Valid when ready.
   • Propagation can take up to 48 hours, but most changes appear within a few minutes.
8. Verify the Setup
   • Open a browser and navigate to https://docs.example.com.
   • Confirm that the lock icon appears, indicating a valid HTTPS connection.
   • Check that internal links navigate correctly and that the page title matches your project’s documentation.
   • Use curl -I https://docs.example.com to verify the HTTP status (should be 200) and that the Server header reports readthedocs.org.

Expected Checks

• DNS Resolution: dig docs.example.com should return the CNAME target docs.readthedocs.io (or the A record IPs).
• TXT Verification: dig TXT docs.example.com must contain the verification token shown in the dashboard.
• Certificate Status: The Custom Domains page should list the domain as Verified and Certificate: Valid.
• Page Load: The custom domain should load the documentation without redirects or errors.

Recovery Options

• Domain Not Verified: Re‑check the TXT record value, ensure no trailing spaces, and confirm TTL propagation. Use dig TXT docs.example.com to verify the record exists.
• HTTP 502 After Force HTTPS: Disable Force HTTPS temporarily, wait for the certificate to be issued, then re‑enable.
• Wrong Base URL: If relative links break, double‑check html_baseurl includes the trailing slash and matches the custom domain exactly.
• DNS Propagation Delays: If the domain still points to the default ReadTheDocs URL after 48 hours, clear your local DNS cache (ipconfig /flushdns on Windows or sudo killall -HUP mDNSResponder on macOS) and retry.

Limitations

• Custom domains are not available on all free‑tier projects unless the feature is explicitly enabled.
• ReadTheDocs issues certificates only for domains that are publicly resolvable; internal or private domains will fail verification.
• Propagation delays can cause intermittent failures; plan deployments during low‑traffic periods.

Practical Verification Checklist

TXT VerificationCertificatePage Load

Step	Verification Action	Expected Result
DNS CNAME	dig CNAME docs.example.com	Points to docs.readthedocs.io
dig TXT docs.example.com	Contains verification token
ReadTheDocs dashboard	Certificate: Valid
Browser visit	Lock icon and correct content

Conclusion

By following the steps above you can confidently map a custom domain to your ReadTheDocs project, ensuring a branded, secure, and fully functional documentation site. Remember to keep DNS records accurate, verify ownership promptly, and update html_baseurl so that internal navigation remains consistent. If anything goes wrong, the recovery options outlined will help you pinpoint and fix the issue quickly.