Docs hosting

Docup does not deploy a site per customer. One Worker serves the app and every docs site, and the host of the request decides which.

From host to site#

The host helper defines the root domains docup.dev and localhost. The parsed address comes from the request's own host when it is exactly one label under a root domain:

Host	Result
acme.docup.dev	acme
acme.localhost:3000	acme
docup.dev, localhost:3000	null (the app)
www.docup.dev, app.docup.dev, api.docup.dev, cname.docup.dev	null (reserved)
a.b.docup.dev	null (more than one label)
a workers.dev preview URL	null

Because the address comes from the request's own host, every screen shows a link that works wherever it is viewed, including acme.localhost:3000 in development.

If the request is on a custom domain (any host that is not Docup's own root domains or a workers.dev preview), the Worker resolves the hostname to its site subdomain. Each isolate caches the resolved subdomain in memory for 60 seconds. On an isolate cache miss, the Worker queries Redis, which caches the resolved subdomain for 600 seconds, falling back to the database.

To prevent search engines from indexing the same site under multiple domains, the Worker redirects GET and HEAD requests on the Docup domain to the active custom domain using a 301 permanent redirect (cached in browsers for 3,600 seconds). The /docup-turnstile path is exempt from this redirect so that bot checks can run on the Docup domain.

The proxy rewrite#

The proxy middleware runs on every request that is not a framework file, an API route, or an asset/social card path. For a docs host it rewrites the URL:

Request	Rewritten to
/robots.txt, /sitemap.xml, /llms.txt, /llms-full.txt	/sites/<address>/<file>
/guides/editor.md	/sites/<address>/docup-md/guides/editor
Any other path with a dot	Left alone, as a static file
/	/sites/<address>
/guides/editor	/sites/<address>/guides/editor

Requests to _next/, api/, docup-asset/ and docup-og are never rewritten, because a rewritten response loses its cache-control.

Subdomain routes#

Route	Serves
Layout	The site frame: header, navigation, theme, brand styles, favicon and the Ask AI widget
Path page	A documentation page, with metadata, structured data and the Markdown body
Markdown page	A page as Markdown
/docup-turnstile	The Ask AI bot check (exempted from custom domain redirects)
Generated files	Sitemap, robots, LLMs manifest files
Not found	The page for a path that does not exist

Each route first calls a verification helper, which checks that the host really belongs to the address in the path. Because the Worker deletes any user-supplied x-docup-site header and overrides it with the parsed address, a site cannot be read by requesting /sites/<address> on the wrong host.

Loading a site#

Loading a live site returns the site's project id, custom domain, navigation, configuration and version, or null when the site does not exist, was never published, or has no live pages. It is wrapped in React's cache, so the layout, page and metadata share one result per request. Loading a published page then reads the text of one page, so a page and each prefetched link stay small.

Navigation uses the live path and position, not the draft ones. If a value is missing, the draft values stand in for them.

If the site is private, hidden or missing, the route answers 404.

Draft preview#

The preview route renders the same frame from the draft columns for people in the workspace. A session check runs first, and draft loaders check that the project belongs to the workspace. The preview carries a noindex, nofollow robots tag and an amber banner.

Assets and social cards#

Uploaded images are stored in R2 under site asset directories and served on the site's host with a one-day cache. Open Graph paths render a 1200 by 630 card for a page. When the owner chose a custom image, it is used instead.

Views#

A view recording function runs after every response on a docs host, via Cloudflare's waitUntil mechanism. See Analytics.