Readers expect product documentation at a URL you control, such as https://docs.example.com, not https://docs.page/acme/handbook. Custom domains map a hostname to a single hosted repository so every page, preview link, and sitemap uses your brand at the root of the path.
A custom domain is a one hostname, one repository mapping. When the mapping is active, production URLs drop the /{owner}/{repo} prefix that appears on the default docs.page host. The same MDX files and docs.json configuration power the site; only the public URL shape changes.
docs.page still fetches content from your public GitHub repository on each request, using the same push-to-publish model as the default host. Custom domains change routing and link generation, not how content is stored or bundled.
Compare with Vanity subdomains, which shorten paths under {owner}.docs.page but keep the docs.page hostname. Custom domains use a hostname you own entirely.
On the default host, production docs live under /{owner}/{repo}:
https://docs.page/acme/handbook
https://docs.page/acme/handbook/installationOn a custom domain for acme/handbook, the same pages are served at the domain root:
https://docs.example.com/
https://docs.example.com/installationBranch preview ref segments work the same way. They move to the front of the path without the owner or repository prefix:
https://docs.example.com/~feature-docs
https://docs.example.com/~feature-docs/installationPer-repo utility routes follow the same pattern: /search.json, /sitemap.xml, /robots.txt, /llms.txt, and /mcp are available at the domain root (or under a ~ref prefix when previewing a ref).
The app maintains hostname-to-repository mappings through a platform-managed registry. docs.page looks up the mapping when rendering canonical URLs and when routing incoming requests on your hostname.
When a domain is registered for your repository, production canonical URLs, sitemap links, and internal link generation point readers at https://{your-domain} instead of https://docs.page/{owner}/{repo}.
Custom domain mappings are managed outside your repository. You do not set the hostname in docs.json; DNS and the platform registry together connect your domain to a hosted repo.
Features that resolve URLs against the current site context respect custom-domain mode automatically:
- Frontmatter redirects resolve relative paths against your custom domain base instead of
docs.page/{owner}/{repo}. - Locales keep the same first-segment locale pattern. Only the host changes (
https://docs.example.com/fr/installation). - Canonical URLs, sitemap links, and internal navigation use your custom domain in production when a mapping is active.
Development and local preview continue to use localhost or the default docs.page host. Custom-domain path rewriting applies in production when a mapping is active for your repository.
Custom domains are available today through manual setup by the docs.page team. Open a GitHub issue on invertase/docs.page with your repository, desired hostname, and DNS context. See Custom domain for what to include.
Self-serve CLI setup (docs domain add) is planned but not available yet.
For a self-serve shorter URL today, use Vanity subdomains — no DNS changes or request required.
For HTTP routes and platform internals once a domain is active, see HTTP endpoints.