Custom Domains for Documentation: Why They Matter and How to Set One Up on Dokly

When a prospective customer lands on your documentation, the URL is the first signal they receive about your company.

docs.stripe.com says: this is a real company, they own their infrastructure, they've been around long enough to care about their docs URL.

acme-corp.docshost.io/docs/v2 says: this company is using a third-party platform, hasn't bothered to set up their own domain, and probably hasn't thought carefully about the rest of the developer experience either.

That's unfair, obviously. The URL says nothing about the quality of the product. But first impressions aren't fair—they're quick, reflexive, and disproportionately weighted. And the URL of your docs is one of the first impressions every potential customer forms.

This post covers why custom domains matter more than most teams realize, the different options (root domain, subdomain, subfolder), and a step-by-step walkthrough of setting one up on Dokly.

Why Custom Domains Matter#

Brand consistency#

Your marketing site is at yourcompany.com. Your app is at app.yourcompany.com. Your blog is at yourcompany.com/blog. Your docs should be at docs.yourcompany.com, not yourcompany.docsplatform.io.

When users move between your properties, the consistent domain reinforces that they're in your ecosystem. When they hit a third-party hostname, there's a tiny cognitive break—"wait, am I still on Acme's site or did I get redirected somewhere?"

Multiplied across every user journey, those tiny breaks add up. Trust, conversion, and retention all improve when your entire experience lives on domains you own.

SEO authority#

Search engines treat subdomains and root domains of your main site as part of your domain authority. Content at docs.yourcompany.com accrues SEO value that compounds with your main site.

Content at yourcompany.docsplatform.io accrues SEO value for the platform, not for you. Their domain ranks; yours doesn't. If you ever migrate off that platform, you lose the rankings you've built.

For documentation—which is often a massive source of organic traffic for developer tools—this difference is significant. A docs site that's well-structured and on your own domain can drive 30–50% of your total organic traffic within a year. A docs site on someone else's subdomain drives 0% of that back to your domain authority.

Trust and credibility#

Security-conscious users check URLs. Enterprise buyers check URLs. Developers check URLs.

A custom domain with a valid SSL certificate and your company's name is a baseline expectation for any serious software product. The absence of one signals either that you're very early-stage or that you're using a platform that doesn't support it. Neither reads as a positive.

Flexibility and portability#

If your docs are at docs.yourcompany.com, you can change the underlying platform at any time without changing the URL. Your links stay live. Your SEO stays intact. Your users don't even notice.

If your docs are at yourcompany.docsplatform.io, you're locked in. Migrating means either breaking every link to your docs that's ever been shared, or maintaining redirects from the old domain indefinitely.

The custom domain isn't just about vanity. It's about keeping your options open.

Root Domain, Subdomain, or Subfolder?#

There are three common patterns for docs URLs. Each has tradeoffs.

Subdomain: docs.yourcompany.com#

Pros:

• Clean separation from your main site
• Independent deployment—you can update docs without touching your marketing site
• Easy to set up with most docs platforms, including Dokly
• Universally understood by users

Cons:

• Subdomains are treated as separate origins by search engines and some tools. The SEO boost is real but not as strong as subfolders.
• Shared cookies and auth can be slightly more complex

Who should use it: Most teams. This is the default choice and the one we recommend unless you have a specific reason for something else.

Subfolder: yourcompany.com/docs#

Pros:

• Maximum SEO benefit—all content lives on the same root domain
• Cookies and auth work seamlessly across the whole site
• Cleanest for small sites where docs are a small part of the experience

Cons:

• Harder to set up, usually requires a reverse proxy (nginx, Cloudflare Workers) to route /docs traffic to your docs platform
• Deployment coordination between your main site and docs is more complex
• Any issue with your docs platform can affect perceived availability of your main site

Who should use it: Content marketing–heavy businesses where docs are a growth channel and maximum SEO matters. Also good for content-focused sites where "docs" is just one section among many.

Root domain: yourcompany.com#

Pros:

• Appropriate when docs are the product (docs platforms, knowledge bases, reference sites)

Cons:

• Only makes sense in narrow cases
• Removes the ability to have a marketing site at the same URL

Who should use it: Very few teams. If you're making an open-source project where docs are the entire website, this might make sense.

The Dokly default: subdomain on a free tier, custom domain on Pro#

Dokly gives you a free subdomain of the form yourname.dokly.co the moment you sign up. For many solo developers and indie projects, that's enough—clean, short, and works out of the box.

Upgrading to Pro unlocks custom domains. You can keep the Dokly subdomain or point your own domain at your docs. Most paid Dokly customers are using subdomains of their main company domain (docs.theircompany.com), with a smaller group using subfolders via reverse proxy.

Setting Up a Custom Domain on Dokly#

The setup takes about ten minutes, most of which is waiting for DNS to propagate. Here's the full flow.

Step 1: Decide on your domain#

Most teams pick docs.yourcompany.com. Other common choices:

• help.yourcompany.com for help-center-style docs
• developers.yourcompany.com for developer portals with multiple sub-sections
• api.yourcompany.com for API-focused reference sites (though this conflicts with using that subdomain for the actual API)

Pick something short and obvious. docs is short and obvious. documentation works but is longer. learn is fine if your docs are heavily tutorial-focused. Avoid clever names that make users guess.

Step 2: Add the domain in Dokly#

In your Dokly dashboard, go to Settings → Custom Domain. Click "Add Domain" and enter your desired hostname, e.g., docs.yourcompany.com.

Dokly will show you a set of DNS records to add. For subdomains, this is usually a single CNAME record pointing to proxy.dokly.co. For root domains (if you're using one), it's an A record or an ALIAS/ANAME record, depending on your DNS provider's capabilities.

Step 3: Add the DNS records at your registrar#

Log into your domain registrar or DNS provider (Cloudflare, Route 53, Namecheap, Porkbun, whoever hosts your DNS) and add the records Dokly gave you.

For docs.yourcompany.com, the record will look like:

Type:  CNAME
Name:  docs
Value: proxy.dokly.co
TTL:   Auto (or 300 seconds if manual)

If you're using Cloudflare, set the proxy status to "DNS only" (grey cloud) initially. Once everything's working, you can optionally switch it to proxied (orange cloud), but Dokly's proxy already handles SSL and caching, so the Cloudflare proxy adds complexity without much benefit.

Step 4: Wait for DNS propagation#

DNS changes take anywhere from a few seconds to a few hours to propagate globally. Usually it's under 10 minutes. You can check progress with dig docs.yourcompany.com from the command line:

dig docs.yourcompany.com
 
;; ANSWER SECTION:
docs.yourcompany.com.    299    IN    CNAME    proxy.dokly.co.

Once the CNAME resolves correctly, you're ready to verify in Dokly.

Step 5: Verify and issue SSL#

Back in the Dokly dashboard, click "Verify" on your domain. Dokly will:

1. Check that the DNS is pointing correctly
2. Issue a Let's Encrypt SSL certificate for your domain
3. Configure the proxy to serve your docs over HTTPS

This step usually takes 30 seconds. Once it completes, you can visit https://docs.yourcompany.com and see your docs.

Step 6: Update internal links#

After your domain is live, update any references to the old Dokly subdomain in your:

• Marketing site navigation and footer
• Product UI (help links, documentation callouts)
• Email templates (welcome emails, onboarding sequences)
• Social media profiles
• README files in your repos

The old subdomain still works, but you want search engines and users on the canonical URL.

Step 7: Set up redirects (for migrations)#

If you're migrating from another docs platform, you'll want to set up redirects from old URLs to new ones. Dokly supports redirect rules in your site settings:

{
  "redirects": [
    { "source": "/old-path", "destination": "/new-path", "permanent": true },
    { "source": "/api/v1/:slug", "destination": "/reference/:slug", "permanent": true }
  ]
}

These preserve your SEO equity and don't break old links anyone has shared.

Advanced Patterns#

Multiple docs sites on one domain#

Some products have multiple docs sites—e.g., separate docs for a REST API, a GraphQL API, and a CLI tool. You can handle this a few ways:

Separate subdomains: rest.docs.yourcompany.com, graphql.docs.yourcompany.com, cli.docs.yourcompany.com. Clean but verbose.

Subfolders within one docs site: docs.yourcompany.com/rest, docs.yourcompany.com/graphql. More common and usually better for SEO.

Dokly supports both. For most cases, keep everything on one site and use sidebar organization to split content.

Staging domains#

For teams with review workflows, you can set up a staging domain—e.g., docs-staging.yourcompany.com—that renders your draft content before it goes live. Useful for reviewing major updates with stakeholders before publishing.

Cloudflare and edge caching#

Dokly's proxy already handles edge caching globally, so adding Cloudflare in front of it usually doesn't help. But if you're using Cloudflare for other reasons—WAF rules, bot protection, specific caching rules—you can run it in proxied mode. Make sure to set "Full (strict)" SSL mode in Cloudflare so the connection to Dokly's origin is encrypted.

IPv6 and modern protocols#

Dokly's proxy supports IPv6, HTTP/2, and HTTP/3 out of the box. You don't need to configure these; they just work. Your docs load fast on any modern network.

Migrating from Another Platform#

If you're coming from Mintlify, GitBook, ReadMe, or another platform, the custom domain migration has a specific sequence to minimize downtime.

Before the switch#

1. Set up your Dokly site at its default subdomain (yourname.dokly.co) and migrate your content. Make sure everything looks right before you touch the domain.

2. Prepare redirects. Export your old site's URL structure and map each URL to its new Dokly equivalent. If paths are different, you'll need redirect rules.

3. Lower your current DNS TTL. A week before the switch, lower the TTL on your current docs domain's records to something short (like 300 seconds). This means DNS changes will propagate quickly when you make them.

On switching day#

1. Update DNS to point at Dokly's proxy instead of your old platform.

2. Verify in Dokly and wait for SSL to issue (usually 30 seconds).

3. Test thoroughly — click through your sidebar, test search, verify internal links, check that code blocks render.

4. Enable redirects for any paths that changed.

5. Monitor your analytics for any spikes in 404s, which indicate URLs you missed mapping.

The total downtime for a well-prepared migration is usually zero—DNS updates without a gap in service. The total migration effort is usually a weekend for a small docs site, a week for a large one.

What You Get at Each Dokly Tier#

Custom domains are a Pro tier feature. Here's the full breakdown:

Free tier:

• yourname.dokly.co subdomain
• Full SSL
• Unlimited pages
• All MDX components
• Auto-generated llms.txt

Pro ($19/month):

• Custom domain (one)
• Remove Dokly branding
• Custom logo and favicon
• Advanced analytics
• Priority support

Team ($49/month):

• Multiple custom domains
• Multi-user editing
• GitHub sync
• Private docs with gated access

Most solo developers on Pro use one custom domain. Growing teams on Team often use multiple—a public docs site on docs.yourcompany.com and a private internal knowledge base on internal.yourcompany.com.

Common Issues and Solutions#

"DNS isn't propagating"#

Usually it's propagated fine, and you're hitting a local DNS cache. Try from a different network (a phone on cellular works), or use https://dnschecker.org to check from multiple global locations.

"SSL certificate won't issue"#

Almost always caused by CAA records blocking Let's Encrypt. Check your DNS for any CAA records—if you have them and they don't include letsencrypt.org, add it:

example.com. IN CAA 0 issue "letsencrypt.org"

"Docs work, but images are broken"#

Check your MDX for absolute URLs pointing to the old domain. Images referenced with the old subdomain URL won't load on the new one. Switch to relative URLs or to your new domain.

"Old URLs return 404"#

You skipped the redirects step. Go back and add redirect rules mapping old paths to new ones.

The Takeaway#

A custom domain is a small investment with outsized returns. It takes ten minutes to set up and it immediately upgrades your brand, your SEO, and the trust signals you send to every user who opens your docs.

There's no good reason to leave your docs on a platform subdomain once you're past the initial validation phase. It's the cheapest professionalism upgrade you'll ever make.

Set up Dokly Pro and point your domain at it. Your next migration—if there ever is one—will be painless because your docs URL will be something you own, not something you rent.

The best documentation URLs are the ones your users never notice. Because they're exactly where they should be.