Skip to main content
NookDocs
Dashboard

Deploy

Custom domain

Point docs.yourcompany.com at your project via CNAME or ALIAS, survive DNS propagation, get Let's Encrypt SSL in seconds, and avoid the common Cloudflare + Vercel gotchas.

Every project ships on a free {slug}.nookdocs.site subdomain. Adding a custom domain is a 3-step flow: type the hostname in the dashboard, copy the DNS record, wait for verification. SSL provisions automatically. This page covers every edge case we've hit: apex domains, CAA records, Cloudflare proxy mode, multi-domain setups, and canonical URL handling for SEO.

Subdomains attach with one CNAME to cname.nookdocs.site; apex domains use ALIAS/ANAME/flattening (or A record 76.76.21.21 as a fallback) since apex CNAMEs are invalid. Verification polls DNS for up to 60 seconds, then Let's Encrypt SSL provisions automatically — no manual cert step. If a CAA record exists it MUST include 0 issue "letsencrypt.org" or issuance fails silently. With Cloudflare, keep the proxy off (grey cloud / DNS only) and set SSL/TLS to Full (strict); a proxied record or Flexible mode breaks tenant resolution and TLS. One domain attaches to one project; the Primary domain drives the <link rel="canonical">, overridable via seo.metatags.canonical in nookdocs.config.json.

Why use a custom domain

Brand consistency

docs.acme.com reads as part of your product; acme-docs.nookdocs.site reads as a third-party tool.

SEO authority

Backlinks accrue to your apex domain, not ours. Custom domains compound your organic search.

User trust

Users are trained to verify the domain bar. A branded host is one fewer phishing signal.

Pick the host shape

Two shapes work out of the box. Pick based on where your docs live in your information architecture.

Subdomain — docs.acme.com

A subdomain of your apex. Add a CNAME record, we verify it, SSL provisions automatically. 90% of setups look like this.

Subpath — acme.com/docs

Hosts your docs as a path prefix of your marketing site. Requires a reverse proxy rule in front of your site. Advanced — see subdomain for the split.

Add via the dashboard

Settings → Domain — type your hostname and add it

Open Settings → Custom domains

Scroll to Custom domains. Empty when you've only been using the default subdomain; otherwise you'll see existing domains with verification state.

Enter your hostname

Type docs.acme.com (or whatever you own) and hit Add. Each project can carry multiple custom domains simultaneously — e.g. docs.acme.com + docs.acme.dev + a regional help.acme.eu — each with its own verification state. Mark one as Primary (see canonical URLs below) and the rest stay aliased.

Copy the DNS record we show you

You'll see something like:

Type  : CNAME
Host  : docs
Value : cname.nookdocs.site
TTL   : 3600 (or Auto)

Copy the Value field — that's what your DNS provider needs.

Add the record at your DNS provider

Open Cloudflare / Route 53 / DNSimple / GoDaddy / Google Domains / Namecheap and paste the CNAME record as shown. Save.

Wait for verification

Our checker polls DNS every 5 seconds for up to 60 seconds. When it catches the propagated record, the domain flips from Pending to Active and SSL provisioning kicks off.

DNS record reference

CNAME — the default case

docs.acme.com.    IN    CNAME    cname.nookdocs.site.

CNAMEs are the simplest case — your provider routes docs.acme.com through us, and everything (TLS, headers, caching) flows end-to-end.

Don't create an A record as well. CNAME + A on the same hostname is invalid per RFC 1034 and most providers reject it.

CAA — required when you have one

If your domain already has a CAA record, it must allow Let's Encrypt. Otherwise our cert issuance fails silently.

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

Check your current CAA:

dig acme.com CAA +short
# → 0 issue "digicert.com"   ← blocks Let's Encrypt
# → no output                  ← no CAA, any issuer allowed ✓

If you see an existing issue entry, add Let's Encrypt alongside it:

acme.com.    IN    CAA    0 issue "digicert.com"
acme.com.    IN    CAA    0 issue "letsencrypt.org"

Apex domain (acme.com)

Apex domains — the bare root without any subdomain — can't use CNAMEs per the DNS spec. Three options, from best to worst:

ALIAS / ANAME / flattening (recommended)

Modern providers (Cloudflare, DNSimple, Route 53) offer a CNAME-like record at the apex that resolves to the target's current IPs on every query.

Cloudflare
acme.com.    CNAME    cname.nookdocs.site.    ; proxy: OFF

Cloudflare users — keep the proxy off. The orange cloud (proxied mode) breaks the SSL handshake by terminating TLS at Cloudflare. Set the record to "DNS only" (grey cloud) so traffic flows end-to-end.

A record fallback

If your provider doesn't support ALIAS, fall back to A records pointing at our published IPs:

acme.com.    IN    A    76.76.21.21

Downsides: IPs can change (90 days notice), and single-A means no multi-region failover. Prefer ALIAS when available.

Subdomain redirect

Dodge the problem entirely — keep your apex as your marketing site, and run docs on a subdomain:

acme.com         → www.acme.com (marketing)
docs.acme.com    → NookDocs (this guide)

SSL

SSL certificates auto-provision via Let's Encrypt (issued through Vercel's edge) the moment verification succeeds.

  • First issuance — usually under 30 seconds after the DNS record goes green.

  • Renewal — automatic, ~30 days before expiry.

  • Issuer — Let's Encrypt R3.

  • Reserved path — /.well-known/acme-challenge/* is reserved for the challenge handshake; don't configure your docs to write content to that path.

Multiple domains per project

Add more than one custom domain to the same project — e.g. regional domains or migration scenarios where both old and new domains need to serve during a cutover.

docs.acme.com         primary    ✓ active
docs.acme.dev                    ✓ active
help.acme.eu                     ✓ active
acme.nookdocs.site    default    ✓ active

All active domains serve the same content. The primary domain drives canonical URLs — see below.

Canonical URLs for SEO

When you have multiple domains serving the same docs, search engines need one canonical URL per page to avoid duplicate-content penalties. NookDocs picks the canonical automatically in this priority order:

  1. The domain marked Primary in Settings → Custom domains

  2. The first verified custom domain in the list

  3. The default {slug}.nookdocs.site subdomain

Every rendered page ships <link rel="canonical" href="https://{canonical-host}/{path}"> so Google/Bing know which URL to index. Override site-wide via nookdocs.config.json:

{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}

See SEO for the full indexing + sitemap + robots story.

Cloudflare-specific gotchas

Vercel verification (if your DNS is managed on Vercel)

Vercel-hosted DNS adds a TXT record during verification. If you manage your DNS on Vercel (most users don't — this is an edge case), you'll see a prompt asking you to add:

_vercel.acme.com.    IN    TXT    "vc-domain-verify=docs.acme.com,abc123..."

Paste into Vercel's DNS panel. We detect the record, verification completes, the TXT record can stay (harmless) or be removed.

Troubleshooting

Related

Was this page helpful?

Last updated August 13, 2026