Custom Domains for Your Docs — Without the Per-Site Markup
How custom domains work in Knowledge, what a claimed domain actually needs before it serves traffic, and why this is a genuine gap versus Notion and GitBook.
Custom domains sound like a checkbox feature until you look at how competitors actually price and scope them. Notion has no custom domain support at all. GitBook offers custom domains starting around $65 per site — workable if you're publishing one documentation site, expensive fast if you're managing docs for multiple products or multiple clients, since neither platform treats multi-tenant documentation as a first-class case. That gap is the actual context for how Knowledge handles this.
How a domain gets claimed
Claiming a custom domain for a Knowledge space is a straightforward POST request that creates a Cloudflare Custom Hostname for that space. The first domain you claim for a given space automatically becomes the primary domain for it — you don't have to separately flag which one is canonical if you're only adding one.
The part worth being honest about
A claimed domain doesn't necessarily mean live traffic immediately. Whether a domain actually routes visitors depends on proxyConfigured — and if the deployment's DOMAIN_PROXY_SHARED_SECRET isn't set, a claimed domain sits in a pending state with no traffic actually routed to it yet. This isn't a hidden failure mode you have to discover the hard way: the route itself surfaces proxyConfigured in its response rather than silently reporting success on a domain that isn't actually serving anything. If you claim a domain and it isn't resolving, check that field before assuming something's broken on the DNS side.
Why multi-space, multi-domain matters specifically for agencies and multi-product teams
The reason this is a genuine competitive gap rather than a marketing claim: Knowledge's underlying architecture is multi-tenant by design — one workspace can run many spaces, each its own docs site with its own slug, navigation, appearance, and optionally its own custom domain (see the companion piece on multi-space docs). That's exactly the shape Docsie's own comparison research calls out as underserved by GitBook and Notion — "consultancies, implementation partners, or any team delivering documentation to multiple clients." A single agency workspace can run a distinct, custom-domained docs site per client without paying a per-site custom-domain fee for each one, because the underlying primitive was built to support many sites from one account rather than one site per account with add-ons bolted on.
Setting one up
Claim the domain against the specific space it belongs to, verify proxyConfigured comes back true (or follow up on the deployment configuration if it doesn't), and point your DNS at the value Cloudflare's Custom Hostname setup expects. If you're running documentation for multiple products or clients, this is worth doing per space from the start rather than consolidating everything into one space and dealing with the split later — spaces are the unit custom domains attach to, and restructuring content across spaces later is more work than starting with the right boundaries.
What this doesn't cover
This is domain claiming and routing, not DNS management on your registrar's side — you still need to create the actual DNS record pointing at Cloudflare. And a pending proxy status is a deployment configuration gap, not something an end user can work around from inside the product; if you hit it, it's worth raising with whoever manages your deployment's environment configuration.