Current
Docs Artifact Compatibility
How published docs versions stay readable as the Doxa renderer changes, and what is not yet covered
Overview
Every published docs version is stored as a versioned artifact: a manifest plus the pages, navigation, and assets that make up the site. The Doxa renderer reads these artifacts to serve your site at <slug>.doxa.page or on a custom domain. This page explains how Doxa keeps existing artifacts readable when the renderer changes, and which parts of that protection are still in progress.
Status: Manifest version checks and reference-artifact test suites are in place. Automated comparison of production component output is deferred. A canary rollout that updates only some sites first is planned but not available.
What Doxa checks today
Doxa treats published artifacts as a contract between the docs generator and the renderer. Before a renderer change ships, the platform checks that it can still read artifacts that were already published.
Manifest version checks. Each artifact declares the schema version it was written with. The renderer reads that version and rejects artifacts it does not understand, rather than rendering them incorrectly.
Reference artifact sets. Doxa keeps a fixed set of sample artifacts and expected outputs. Each set is frozen once added, so a renderer change cannot quietly rewrite the expectation.
The reference sets cover three cases:
| Set | What it represents |
|---|---|
| Starter site | A two-page site with flat navigation. |
| Component showcase | Two sections, grouped navigation, every MDX component, and one API reference page. |
| Legacy artifact | A site published before the manifest carried a schema version. |
These checks cover the behaviors listed above. They do not prove that every component looks or behaves the same in production.
Known limits
Two gaps remain, and you should plan around them:
Production component output is not compared automatically. The current checks confirm that pages render and that component names resolve. They do not confirm every prop, style, or interaction. A component can lose support for a prop while the checks still pass. Review your pages after a renderer update, especially pages that use Tabs, FileTree, Mermaid, or Card layouts.
Renderer updates reach all sites at once. Canary rollout, where a subset of sites receives a new renderer first, is planned but not built. Treat each renderer update as applying to every published site.
Note:
Because renderer updates are not staged, check your most important pages on your published site after an update. If something breaks, publish a corrected branch to restore the site.
What this means for your site
Published versions keep their artifacts. Use publication history to restore an earlier version if a page regresses. See Branches, Previews, Publishing, and Restore.
Use a preview before you publish. A branch preview shows how your pages render with the current renderer. See Editing Pages in the Content Editor.
If you use a custom domain, confirm the domain still serves your docs after an update. See Custom Domains.
Related pages
The runtime concepts behind generation, versioned artifacts, and publishing.
How published pages are rendered for readers.
Where versioned docs content is stored.
Preview, publish, and roll back docs changes.