Custom Domain Support

Master this essential documentation concept

Quick Definition

The ability to publish documentation or portals using a custom web address (domain name) instead of a platform-provided subdomain, enabling branded customer experiences.

How Custom Domain Support Works

flowchart TD A[User Types docs.yourcompany.com] --> B{DNS Lookup} B --> C[CNAME Record Points to Platform] C --> D[Documentation Platform Server] D --> E{SSL Certificate Valid?} E -->|Yes| F[Serve Documentation Content] E -->|No| G[Provision SSL via Let's Encrypt] G --> F F --> H[User Sees Branded Documentation] subgraph DNS_Config [DNS Configuration] I[Domain Registrar] J[Add CNAME Record] K[docs.yourcompany.com → platform.docshost.io] I --> J --> K end subgraph Platform_Setup [Documentation Platform Setup] L[Enter Custom Domain] M[Verify Domain Ownership] N[Enable HTTPS] L --> M --> N end DNS_Config --> B Platform_Setup --> D style A fill:#4A90D9,color:#fff style H fill:#27AE60,color:#fff style DNS_Config fill:#F8F9FA,stroke:#dee2e6 style Platform_Setup fill:#F8F9FA,stroke:#dee2e6

Understanding Custom Domain Support

Custom Domain Support allows documentation teams to host their knowledge bases, API references, and developer portals under a company-owned domain name rather than the default subdomain provided by a documentation platform. This capability bridges the gap between third-party documentation tools and a cohesive brand experience, making documentation feel like an integral part of the product rather than an external resource.

Key Features

  • CNAME and A Record Configuration: Enables DNS-level mapping of your custom domain to the documentation platform's servers
  • SSL/TLS Certificate Management: Automatic or manual provisioning of HTTPS certificates for secure documentation delivery
  • Subdomain Flexibility: Support for multiple subdomains (docs.company.com, help.company.com, api.company.com) pointing to different documentation portals
  • Redirect Management: Handles canonical URLs and redirects to prevent duplicate content and broken links
  • CDN Integration: Custom domains often work with content delivery networks for faster global documentation access

Benefits for Documentation Teams

  • Brand Consistency: Documentation URLs match your product's domain, reinforcing brand identity at every touchpoint
  • User Trust: Readers are more likely to trust and engage with documentation hosted on a recognizable company domain
  • SEO Advantages: Documentation content contributes to your primary domain's search authority rather than the platform's domain
  • Analytics Consolidation: Easier to track user journeys across product and documentation when sharing a root domain
  • Vendor Independence: Switching documentation platforms becomes less disruptive when your public-facing URL remains unchanged

Common Misconceptions

  • It requires advanced technical skills: Most modern platforms provide step-by-step DNS configuration guides that non-developers can follow
  • Custom domains are only for large enterprises: Even small teams benefit from branded documentation URLs for professional credibility
  • SSL certificates must be purchased separately: Many documentation platforms include free SSL provisioning through Let's Encrypt or similar services
  • Migration breaks existing links: Proper redirect configuration ensures legacy URLs continue to function during and after transitions

Real-World Documentation Use Cases

SaaS Product Documentation Portal Branding

Problem

A SaaS company launches their help center using a documentation platform, but all URLs display as company.docsplatform.com. Sales prospects and customers notice the third-party domain, reducing confidence in the product's maturity and creating a disjointed experience from the main product at company.com.

Solution

Configure a custom domain (help.company.com) using CNAME records to map the documentation platform to the company's owned domain, enabling a seamless branded experience.

Implementation

1. Log into your domain registrar (GoDaddy, Namecheap, Cloudflare, etc.) 2. Navigate to DNS management and add a CNAME record: help → your-docs-platform-alias.io 3. In the documentation platform admin panel, navigate to Settings > Custom Domain 4. Enter help.company.com and click Verify 5. Enable automatic SSL certificate provisioning 6. Test the domain by visiting help.company.com and confirming HTTPS is active 7. Update all internal links, email templates, and product UI to reference the new URL 8. Set up redirects from old platform URLs to new custom domain URLs

Expected Outcome

Documentation is accessible at help.company.com with valid HTTPS, brand-consistent URLs appear in support tickets and product UI, SEO value accrues to the company domain, and customer trust metrics improve as the documentation feels native to the product.

Developer API Documentation with Versioned Subdomains

Problem

A developer tools company maintains API documentation for multiple product versions. Using platform subdomains makes it impossible to structure URLs logically (api-docs.company.com/v1, api-docs.company.com/v2), and developers frequently share incorrect or outdated links because the URLs are unmemorable.

Solution

Implement custom domain support with a dedicated subdomain (api-docs.company.com) and use the documentation platform's version management features to serve versioned content under clean, predictable URL paths.

Implementation

1. Create a dedicated subdomain api-docs.company.com in DNS with CNAME pointing to the platform 2. Configure the documentation platform to recognize this custom domain 3. Set up version-specific URL paths within the platform (/v1, /v2, /latest) 4. Create a landing page at api-docs.company.com that routes developers to appropriate versions 5. Implement 301 redirects from deprecated version URLs to current versions 6. Add canonical tags to prevent duplicate content issues across versions 7. Update SDK documentation, changelogs, and README files with new URLs 8. Configure Google Search Console for the new subdomain to monitor indexing

Expected Outcome

Developers can reliably reference api-docs.company.com/v2/endpoints in code comments and Stack Overflow answers, reducing support tickets about broken documentation links by an estimated 40% and improving developer onboarding completion rates.

Multi-Product Company with Unified Documentation Hub

Problem

A company with three distinct software products (ProjectA, ProjectB, ProjectC) has documentation scattered across different platform subdomains. Customers using multiple products struggle to navigate between documentation sets, and the company cannot present a unified knowledge experience.

Solution

Create a unified documentation hub at docs.company.com with product-specific subpaths or subdomains, using custom domain support across documentation instances to create a cohesive navigation experience.

Implementation

1. Register docs.company.com as the primary documentation hub 2. Configure three documentation instances with custom domains: docs.company.com/projecta, docs.company.com/projectb, docs.company.com/projectc 3. If the platform supports it, use a single documentation workspace with product-specific sections; otherwise configure DNS routing rules 4. Create a custom landing page at docs.company.com root that links to all product documentation 5. Implement consistent navigation headers across all documentation instances showing all products 6. Set up cross-product search if the platform supports federated search 7. Configure analytics to track cross-product documentation journeys 8. Create a shared sitemap.xml that includes all product documentation URLs

Expected Outcome

Customers experience a unified documentation ecosystem, cross-sell opportunities increase as users discover related products through documentation, and the company's documentation domain becomes a trusted authority in search results for all product-related queries.

Documentation Platform Migration Without Breaking Links

Problem

A documentation team needs to migrate from one platform to another, but thousands of external links, support tickets, and indexed Google search results point to the old platform's subdomain URLs. A hard cutover would break all existing links and destroy accumulated SEO value.

Solution

Use custom domain support on the new platform to maintain the same public-facing URLs throughout and after migration, ensuring zero link breakage and preserving SEO equity.

Implementation

1. Before migration, set up the custom domain on the new documentation platform 2. Export all existing content from the old platform with URL mappings 3. Import content to the new platform, preserving URL slugs and structure 4. Configure the custom domain (docs.company.com) to point to the new platform via CNAME update 5. Set up 301 redirects for any URLs that must change structure 6. Perform a crawl of the old platform URLs before DNS cutover to create a complete redirect map 7. Update DNS TTL to 5 minutes 48 hours before migration for faster propagation 8. After DNS cutover, monitor 404 errors in analytics for 30 days and create redirects for any missed URLs 9. Submit updated sitemap to Google Search Console

Expected Outcome

Migration completes with zero public-facing URL changes, all existing links continue to function, Google Search Console shows no significant drop in indexed pages, and the team transitions to the new platform without customer-facing disruption.

Best Practices

✓ Plan Your Subdomain Architecture Before Configuration

Before setting up custom domains, map out your entire documentation ecosystem to determine how many subdomains you need and how they should be structured. Changing subdomain structures after launch creates redirect complexity and potential SEO damage.

✓ Do: Create a documentation URL taxonomy document that defines all subdomains (docs.company.com, api.company.com, help.company.com) and their purposes before touching DNS settings. Consider future product lines and documentation types when planning.
✗ Don't: Don't configure custom domains ad-hoc as new documentation needs arise. Avoid using generic names like docs1.company.com or temp-docs.company.com that will need to be changed later, and don't use hyphens excessively in subdomains as they reduce memorability.

✓ Always Enable and Enforce HTTPS on Custom Domains

Security is non-negotiable for documentation portals, especially those containing API keys, authentication guides, or sensitive configuration instructions. HTTPS also signals trustworthiness to readers and is a confirmed Google ranking factor.

✓ Do: Enable SSL certificate provisioning immediately after configuring your custom domain. Configure HTTP-to-HTTPS redirects so all traffic is automatically secured. Use HSTS (HTTP Strict Transport Security) headers if your platform supports it. Verify certificate renewal is automatic to prevent expiration.
✗ Don't: Don't launch a custom domain without HTTPS configured, even temporarily. Don't use self-signed certificates for public documentation portals. Avoid manual certificate management processes that rely on calendar reminders for renewal, as expired certificates break user trust immediately.

✓ Set Up Comprehensive URL Redirect Mapping

Every URL change in documentation has downstream consequences: broken links in support tickets, GitHub READMEs, blog posts, and user bookmarks. Proactive redirect management prevents documentation dead-ends that frustrate users and harm SEO.

✓ Do: Maintain a redirect spreadsheet that maps every old URL to its new destination. Implement 301 (permanent) redirects for moved content and 302 (temporary) redirects for content being reorganized. Audit your redirects quarterly to remove redirect chains (A→B→C should become A→C). Monitor 404 errors in Google Search Console weekly after any domain changes.
✗ Don't: Don't delete pages without setting up redirects. Don't use 302 redirects for permanently moved content, as this fails to transfer SEO value. Avoid creating redirect loops (A→B→A) which cause browser errors. Don't let redirect chains grow beyond two hops as they slow page load times.

✓ Verify DNS Propagation Before Announcing the New Domain

DNS changes can take anywhere from minutes to 48 hours to propagate globally. Announcing a new documentation URL before propagation is complete means some users will see errors while others see the new content, creating a confusing and unprofessional experience.

✓ Do: Use DNS propagation checker tools (whatsmydns.net, dnschecker.org) to verify your custom domain resolves correctly from multiple global locations before any public announcement. Reduce DNS TTL to 300 seconds (5 minutes) at least 48 hours before making DNS changes to speed up propagation. Test the custom domain from multiple devices and networks before launch.
✗ Don't: Don't announce new documentation URLs in product release notes or emails until DNS propagation is confirmed globally. Don't assume propagation is instant because it worked on your local machine. Avoid making DNS changes on Friday afternoons when your technical team may not be available to troubleshoot issues over the weekend.

✓ Document Your DNS Configuration Internally

DNS configurations for documentation platforms are often set up by one person and then forgotten until something breaks. When team members change or platforms are updated, undocumented configurations become critical knowledge gaps that cause extended outages.

✓ Do: Create an internal runbook that documents every DNS record related to documentation (CNAME values, A records, TXT verification records), which team member owns each domain, renewal dates for any manually managed SSL certificates, and step-by-step instructions for updating configuration if the documentation platform changes. Store this in a location accessible to multiple team members.
✗ Don't: Don't store DNS credentials or configuration details only in one person's email or personal notes. Don't skip documenting TXT verification records added for domain ownership proof, as these are easy to forget and may be needed again. Avoid giving DNS access to only one team member without a documented succession plan.

How Docsie Helps with Custom Domain Support

Book a Demo

Build Better Documentation with Docsie

Join thousands of teams creating outstanding documentation

Book a Demo