By default a custom domain is a subdomain (docs.acme.com) pointed at us
with a CNAME. Subpath hosting instead serves your docs under a path of your
existing site — acme.com/docs — with your own infrastructure in front. Great
when you want docs and marketing under one domain for SEO and brand.
How it works
You keep acme.com on your own platform and add a small reverse proxy that
forwards just the docs path to NookDocs:
Visitor → acme.com/docs/guide
→ your proxy (Cloudflare / Vercel / CloudFront)
→ acme.nookdocs.site/docs/guide (+ two headers)
→ NookDocs renders, prefixing every link/asset/canonical with /docsThe proxy tags each forwarded request with two headers we read:
| Header | Value | Purpose |
X-Nookdocs-Host | acme.com | Your canonical domain — used for <link rel="canonical">, sitemap, OG. |
X-Nookdocs-Base-Path | /docs | The subpath — stripped for routing, re-prefixed on every emitted URL. |
Everything the site emits — navigation, prev/next, breadcrumbs, the logo, page
images, sitemap.xml, llms.txt, JSON-LD, canonical tags — is automatically
prefixed with your subpath, so links stay inside acme.com/docs.
Set it up
Enable subpath on the domain
In Settings → Domains, flip Host at /docs, enter your apex
(acme.com) and the path (/docs), and add it. No CNAME or certificate on
our side — your proxy fronts it.
Add the reverse proxy
Copy the snippet for your platform and deploy it on your domain. Per-provider guides:
Check the headers (CSP)
If your site sends a Content-Security-Policy, make sure it doesn't block the docs assets — see CSP configuration.
The project's origin is always <your-subdomain>.nookdocs.site. The proxy
forwards to it and keeps the /docs path; we strip it for routing and
re-prefix it on output. Your repo, content, and config are unchanged — subpath
is purely a serving choice.
Subpath vs subdomain
Subdomain — docs.acme.com
One CNAME to cname.nookdocs.site, we provision the certificate. Simplest;
no proxy to maintain.
Subpath — acme.com/docs
Docs + marketing share one domain (better for brand + SEO consolidation). You run a small reverse proxy; we never touch your DNS.