Skip to main content

Docs Build And Render Drift Checklist

The docs-index verifier catches missing QA links and common Markdown shape problems, but it is not a full Docusaurus build, MDX transform, sidebar, or asset-render proof. Use this checklist when docs content, sidebars, static assets, API-reference generation, or QA evidence docs change.

Commands​

Run the automated index guard first:

./scripts/local-validation/qa.sh test docs-index

Run the automated docs build/render contract:

./scripts/local-validation/qa.sh test docs-render

For live local Docusaurus render proof, run the same scope with build execution enabled and record any dependency/toolchain failure as a QA finding:

QA_DOCS_RENDER_RUN_BUILDS=1 ./scripts/local-validation/qa.sh test docs-render

If using the existing private docs Bazel target instead, record the equivalent build command and output path:

bazel build //docs/private-docs:build

If the public docs changed, run the documented public Docusaurus build command for the current branch and record the command used. If no Bazel target exists for the public docs on the branch, mark that as a remaining tooling gap instead of treating the private docs build as public-docs evidence.

Manual Render Checks​

  • Open the generated private docs site or local dev server and verify the changed pages render without MDX compile errors, blank pages, hydration warnings, or broken API-reference components.
  • Visit every changed private-docs page directly by URL and through the sidebar or category path that should expose it.
  • When public docs changed, repeat direct URL and navigation checks for the public docs site.
  • Confirm new pages have the expected title, table of contents, previous/next links where applicable, and no duplicate or misleading sidebar labels.
  • Confirm moved or renamed pages leave no stale sidebar entries, category labels, breadcrumbs, or cross-doc links.
  • Confirm code fences render with the intended language and do not swallow following sections.
  • Confirm MDX-specific content, imported components, admonitions, tables, and API docs plugin output render in the built site, not only in Markdown preview.
  • Confirm static images and icons load from static/ paths, have stable dimensions in the rendered page, and are not broken by case-sensitive paths.
  • Confirm image alt text or adjacent captions identify the evidence being shown when the image is part of a QA handoff.

Evidence To Record​

Each docs build/render run should record:

  • branch and commit SHA
  • ./scripts/local-validation/qa.sh test docs-index result and report path
  • ./scripts/local-validation/qa.sh test docs-render result and report path
  • live docs-render command used, or exact reason live build execution was skipped
  • private docs build command, result, and relevant Bazel output path
  • public docs build command and result when public docs changed
  • pages manually opened by direct URL
  • sidebar/category paths manually clicked
  • screenshots or browser notes for MDX/API component pages and image-heavy pages
  • any skipped public/private render check with the exact reason
  • remaining drift risks that are still manual-only

Boundary​

This checklist is manual evidence for docs build/render drift. It does not add new verifier automation, does not prove deployed Cloudflare Pages behavior, and does not replace lane owner review for the accuracy of the underlying content.