Vanity subdomains

If your GitHub organization publishes documentation in several repositories, the default docs.page/{owner}/{repo} URL repeats the owner on every link. Vanity subdomains move that segment into the hostname so each repo gets a shorter path under your org.

Every hosted docs.page site has a canonical URL on the main domain:

https://docs.page/{owner}/{repo}
https://docs.page/{owner}/{repo}/{page-path}

Vanity subdomains add a second public shape for the same content. The GitHub owner becomes the subdomain, and the path starts at the repository name:

https://{owner}.docs.page/{repo}
https://{owner}.docs.page/{repo}/{page-path}

For example, https://docs.page/acme/handbook and https://acme.docs.page/handbook serve the same site. A page at docs/usage.mdx is /usage on either URL shape.

Vanity subdomains require no configuration. If your repository is public and the subdomain matches your GitHub owner or organization name, the shorter URL works immediately. One subdomain covers every public docs repo under that owner.

See Public GitHub hosting for how owner and repository segments resolve to GitHub content.

Both forms fetch the same docs.json and MDX files from GitHub. docs.page picks the request mode from the hostname:

1. A request to {owner}.docs.page maps the subdomain to a GitHub owner
2. The path after the hostname is treated as /{repo}/… instead of /{owner}/{repo}/…
3. Internal links, search, sitemaps, and redirects use the vanity path shape while you stay on the subdomain

Canonical URLs on docs.page/{owner}/{repo} still work. Use whichever shape fits your links and branding.

The subdomain is tied to the GitHub owner, not a single repository. If acme owns handbook, api, and sdk, all three are available under the same hostname:

https://acme.docs.page/handbook
https://acme.docs.page/api
https://acme.docs.page/sdk

Each repository keeps its own docs.json, sidebar, and page tree. The vanity hostname is shared identity for the organization; the first path segment selects the repo.

Branch preview ref segments work on vanity URLs the same way they do on canonical URLs. Add ~{ref} immediately after the repository name:

https://{owner}.docs.page/{repo}~{ref}
https://{owner}.docs.page/{repo}~{ref}/{page-path}

For example, https://acme.docs.page/handbook~feature-docs serves the feature-docs branch of acme/handbook. Numeric refs still resolve to pull request head branches through the GitHub API.

These hostnames stay on the main docs.page site and do not map to a GitHub owner:

• docs.docs.page
• www.docs.page
• staging.docs.page

Nested subdomains (for example team.acme.docs.page) are not supported. The owner segment must be a single label before .docs.page.

Vanity subdomains keep you on the docs.page domain with a shorter path. Custom domains serve docs on a hostname you control (for example docs.acme.com) and drop both the owner and repository from public paths when configured.

Use vanity URLs when a branded docs.page subdomain is enough. Use a custom domain when readers should never see docs.page in the address bar.