Current
Production Docs Caching
How published docs sites are cached, how publishing refreshes readers' pages, and how to check responses
Production Docs Caching
Published docs sites are cached at the edge so readers get faster page loads. When you publish a new version, Doxa removes the cached pages for that site so the next reader sees the new content. You do not configure the cache. This page explains what to expect after you publish, how to check which renderer and cache answered a request, and what happens when a custom domain is removed.
The cache applies to public docs sites at <slug>.doxa.page and to custom domains. It does not apply to the Doxa dashboard.
What is cached
Doxa caches public HTML pages. Other request types keep their original behavior and are not stored in the shared HTML cache.
| Request type | Shared HTML cache | Notes |
|---|---|---|
Public page, such as /overview, requested with Accept: text/html | Yes | Served from the cache after the first render |
Requests that include cookies or an Authorization header | No | Original behavior is kept |
| Search, health, chat, and Markdown requests | No | Original behavior is kept |
| Preview domains and permanent generation URLs | No | These always use the shared renderer |
A root redirect is not cacheable.
What happens when you publish
Each publish event refreshes the cached pages for the site:
You publish a branch from the dashboard or with the
publish_branchMCP tool. Promoting an older version and publishing from the web editor also trigger a refresh.Doxa records a cache invalidation task for the site.
Doxa removes the cached pages, and the next request renders the new version.
If removing the cached pages fails temporarily, Doxa retries the task in a later scheduled run. You do not need to publish again.
If a reader still sees an older page shortly after a publish, reload the page after a short wait. To confirm which version is live, check Publication history as described in Branches, Previews, Publishing, and Restore.
Check which renderer and cache answered
Request a public page with curl to read the diagnostic headers:
curl -sI -H "Accept: text/html" https://your-project.doxa.page/overviewThe response can include these headers:
| Header | Meaning |
|---|---|
x-doxa-host-cache | Cache status of the hostname lookup, copied from Cloudflare when present |
x-doxa-html-cache | Cache status of the HTML response, copied from Cloudflare when present |
x-doxa-renderer-mode | Which renderer produced the response: the dedicated renderer or the shared fallback |
Header values have these meanings:
| Value | Meaning |
|---|---|
HIT or MISS | The cache status Cloudflare reported |
BYPASS | The cache entry point was not used |
UNAVAILABLE | The cache was invoked, but Cloudflare reported no status. This does not mean a cache hit. |
On a fallback response, x-doxa-html-cache describes the attempted dynamic response, not the fallback. Use x-doxa-renderer-mode to tell them apart.
Note:
A HIT header does not measure speed. To see the effect of caching, compare how long a page takes to load shortly after a publish with how long it takes later.
Custom domains
Cache lookups are tied to the hostname that serves the site. When you remove a custom domain, or the domain stops being eligible for routing, Doxa invalidates the old hostname mapping, so requests to that hostname no longer serve your site. To add or remove a domain, see Custom Domains.
Your <slug>.doxa.page address and each custom domain serve the same published version, with links that point to their own hostname.