Mapping a Custom Domain to Your GitBook Documentation

Problem: Generic subdomains dilute brand identity

When a documentation space lives on GitBook’s default *.gitbook.io URL, readers see a generic address that does not reflect your product or company brand. This can cause confusion, especially when you share links in marketing materials or support tickets.

Thesis: GitBook’s custom‑domain feature lets you replace the subdomain with a branded URL while keeping the same editing, versioning, and collaboration workflow.

Setup process overview

1. In GitBook, open the space settings and navigate to the Domain section.
2. Enter the fully qualified domain you want to use (e.g., docs.example.com).
3. GitBook displays a target hostname (typically cname.gitbook.com) that you must point to with a DNS CNAME record.
4. Add the CNAME record in your DNS provider’s console, wait for propagation, then enable automatic HTTPS in GitBook.

Worked example: mapping docs.example.com

Assume you own the domain example.com and have access to its DNS zone.

1. Add the domain in GitBook

   # In GitBook UI: Space Settings → Domain → Add domain
   # Enter: docs.example.com
   # GitBook shows target: cname.gitbook.com
   

   Permission needed: Admin role on the GitBook space.
2. Create the DNS CNAME

   # Example using BIND‑style zone file
   # docs.example.com.  IN  CNAME  cname.gitbook.com.
   

   Where to run: Your DNS provider’s management console or via CLI if you control the zone (e.g., nsupdate). Risk: An incorrect CNAME will cause the domain to resolve to the wrong server, making the documentation unreachable.
3. Verify DNS propagation

   # Run from any machine with dig or nslookup
   # Replace with your actual domain
   $ dig docs.example.com CNAME +short
   # Expected output: cname.gitbook.com
   
   $ nslookup -type=CNAME docs.example.com
   # Expected output: canonical name = cname.gitbook.com.
   

   Check: If the output does not show cname.gitbook.com, wait a few minutes and re‑run; propagation can take up to several hours depending on TTL.
4. Enable HTTPS in GitBook After the CNAME resolves, return to GitBook → Space Settings → Domain and click Verify domain. GitBook will attempt to provision a certificate via Let’s Encrypt. When successful, a padlock icon appears in the browser.

Trade‑off / limitation

• Plan requirement: Custom domains are only available on GitBook Pro or Enterprise plans; the Free plan does not expose this setting.
• Propagation delay: DNS changes may take from a few minutes to several hours. During this window, some users may see the old *.gitbook.io URL while others see the new domain, potentially leading to inconsistent access.
• Misconfiguration risk: An incorrect CNAME or forgetting to re‑enable HTTPS after a DNS change can render the documentation inaccessible until the error is corrected.

Verification and closing actions

1. DNS check: Use dig or nslookup as shown above to confirm the CNAME points to cname.gitbook.com.
2. Browser check: Visit https://docs.example.com and verify the SSL padlock and that the GitBook space loads correctly.
3. GitBook verification: In the Space Settings → Domain panel, ensure the status reads “Verified” and HTTPS is active.
4. Update references: Change any internal links, bookmarks, or integration points (e.g., CI/CD pipelines that publish to GitBook) to use the new custom domain.
5. Monitor: Review access logs or analytics for a few days to confirm traffic is arriving at the expected URL and that error rates remain low.

Once these steps are complete, your documentation will carry a consistent, branded address while retaining GitBook’s collaborative authoring and version‑control features.