Skip to main content

Documentation Build And Render Checklist

Use this checklist when documentation content, sidebars, Docusaurus configuration, static assets, MDX components, or API-reference inputs change. The index validator is necessary but does not compile either site.

Automated Proof​

Build both sites with Bazel​

The maintained build targets are:

bazel build \
  //docs/private-docs:build \
  //docs/public-docs:build

Successful outputs are available under:

  • bazel-bin/docs/private-docs/build
  • bazel-bin/docs/public-docs/build

Always name the site and target in the handoff. Do not use the private target as public-site evidence or report that the public site lacks Bazel coverage.

Run the focused repository validators​

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

The scopes write timestamped reports to:

  • .dev-logs/qa/reports/docs-index-<UTC timestamp>.md
  • .dev-logs/qa/reports/docs-render-<UTC timestamp>.md

scripts/qa/verify_docs_render.py checks both sites. It verifies readable package metadata, the declared Docusaurus build contract, the private OpenAPI generation contract, the public typecheck contract, required config/sidebar files, docs roots, sidebar categories and document IDs, and the local Docusaurus CLI. The focused wrapper runs this in contract mode; its warning that no live build was run is expected when the Bazel builds above are recorded as the live compile proof.

The docs-render contract requires a workspace-local CLI at docs/<site>/node_modules/.bin/docusaurus for each site. Ensure the repository's normal dependency bootstrap has materialized those executables before running the validator. If exactly one local CLI check is absent, record it as an environment finding and rerun after restoring that prerequisite; report the site's Bazel build separately as compile evidence rather than substituting a direct package-manager build.

The validators' own fixture tests are separate Bazel targets:

bazel test \
  //scripts/qa:verify_docs_index_test \
  //scripts/qa:verify_docs_render_test

Those tests protect verifier behavior. They do not validate the current docs content or replace the two qa.sh commands.

Local Browser Proof​

Build success proves Docusaurus and MDX compilation. A browser check still owns navigation, layout, hydration, and asset evidence.

From the repository root, build both sites first:

bazel build \
  //docs/private-docs:build \
  //docs/public-docs:build

Then serve each generated site from a separate terminal with Python's standard-library static HTTP server:

python3 -m http.server 3000 --directory bazel-bin/docs/private-docs/build
python3 -m http.server 3001 --directory bazel-bin/docs/public-docs/build

The //docs/private-docs:start and //docs/public-docs:start targets are not the browser-proof commands until the known dev-server double-chdir and path-to-regexp incompatibility is fixed. Do not publish or depend on fragile JS_BINARY__CHDIR or Node preload shims; serve the Bazel build outputs instead.

For each changed page:

  1. Open the page directly by URL.
  2. Reach it again through the intended sidebar/category path.
  3. Reload on the direct URL and confirm the route remains valid.
  4. Check the browser console for MDX, hydration, React, or asset errors.
  5. At desktop and narrow widths, confirm the title, table of contents, sidebar, code blocks, tables, admonitions, and previous/next controls are usable.
  6. Follow every changed local link and inspect every changed image or icon.
  7. For generated API pages, open a representative operation and confirm the endpoint component, schema, examples, and code samples render.

Stop each static HTTP server when evidence is complete.

Navigation And Content Checks​

  • Every explicit ID in docs/private-docs/sidebars.ts and docs/public-docs/sidebars.ts resolves to the intended maintained page.
  • Sidebar labels are unique, current, and ordered for the reader's task.
  • Historical or intentionally unpublished material is absent from active navigation without being rewritten as current guidance.
  • Moved or renamed pages leave no stale sidebar item, breadcrumb, category link, or cross-document reference.
  • Heading levels and generated anchors are stable; direct links land on the intended section.
  • Code fences use the intended language and do not consume the following section.
  • Tables remain readable on a narrow viewport.

MDX, API, And Asset Checks​

  • Imported MDX components render in the site, not only in a Markdown preview.
  • Admonitions and embedded JSX have no blank output or hydration mismatch.
  • Private API-reference pages match the current configured OpenAPI specification paths and expose no stale operation page.
  • Images and icons load from the correct case-sensitive path.
  • Images have useful alt text or an adjacent evidence caption.
  • Large media does not overflow its container or cause avoidable layout shift.
  • Favicons, manifests, custom CSS, and other configured static references load without a browser 404.

Evidence To Record​

A complete docs QA handoff contains:

  • branch and commit SHA
  • exact Bazel targets and their results
  • relevant bazel-bin/docs/<site>/build output paths
  • docs-index and docs-render report paths
  • direct URLs opened for each changed page
  • sidebar/category paths clicked for each changed page
  • browser and viewport used
  • screenshots or concise browser notes for MDX/API-component and image-heavy pages
  • console or network errors, including confirmation when none were observed
  • any manual check not run, with the exact reason and owner for follow-up

Pass Criteria​

Pass only when:

  1. Both focused validators pass.
  2. Every affected site's Bazel build succeeds.
  3. Changed pages load directly and through navigation without console errors.
  4. Changed MDX/API components and assets render correctly.
  5. Any unperformed deployed-environment check is explicitly classified as remaining manual evidence rather than silently treated as covered.

This checklist does not prove the accuracy of the underlying procedure and does not replace deployed Cloudflare Pages smoke testing when deployment behavior is part of the change.