Documentation Index And Navigation Verification

The documentation index guard checks the maintained QA index and the Docusaurus navigation/configuration contract for both documentation sites. Its implementation is scripts/qa/verify_docs_index.py; the supported focused entry point is the local-validation QA wrapper.

Sites In Scope

Site	Sidebar	Content root	Bazel build
Private docs	docs/private-docs/sidebars.ts	docs/private-docs/docs	//docs/private-docs:build
Public help center	docs/public-docs/sidebars.ts	docs/public-docs/docs	//docs/public-docs:build

Both sidebars are active inputs. A private build is not evidence for the public site, and a public build is not evidence for the private site.

Focused Verification

Build both Docusaurus sites through Bazel first:

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

Then run the repository-content validator:

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

The wrapper writes a timestamped report to .dev-logs/qa/reports/docs-index-<UTC timestamp>.md. This focused scope is also included in the broader governance QA scope, but the focused command is the right rerun while editing documentation.

The validator's own unit tests are Bazel targets:

bazel test //scripts/qa:verify_docs_index_test

That target proves the validator behavior with fixtures. It does not replace qa.sh test docs-index, which checks the current repository content.

What The Validator Checks

QA index completeness

The canonical QA entry point is docs/private-docs/docs/qa/checklists/README.md. The validator requires:

• every top-level docs/private-docs/docs/qa/*.md page to be linked in the Supporting QA docs section
• every checklist under docs/private-docs/docs/qa/checklists/ to have a row in the checklist table
• no link or table row to reference a missing QA page

Retired historical ledgers are not part of this active index contract.

Private and public navigation

For both sidebars.ts files, every explicit document ID must resolve to one of:

• <id>.md
• <id>.mdx
• <id>/index.md
• <id>/index.mdx

The validator also requires each sidebar to contain renderable document items. It catches a stale sidebar ID, but it does not decide whether an intentionally unlisted historical page should be published.

Docusaurus configuration

For each site, the validator reads docusaurus.config.ts and verifies:

• the configured docs root exists
• referenced sidebar, custom CSS, favicon, static image/manifest, and OpenAPI specification paths resolve inside the repository
• no checked configuration reference escapes the repository root

QA Markdown shape and references

Across all QA Markdown pages and checklists, it checks:

• local Markdown links resolve
• repository-root links under docs/private-docs/ and docs/public-docs/ resolve
• local Markdown image references resolve
• fenced code blocks are balanced
• heading levels do not skip downward by more than one level
• generated heading slugs are unique within each page

Fix Workflow

When the validator fails:

1. Open the timestamped report and fix the first concrete missing or stale path.
2. If a QA page was added or removed, update the checklist README in the same change.
3. If a published page moved, update its owning sidebar and all checked links; do not leave an alias or duplicate page unless redirect behavior is explicitly required.
4. Rerun ./scripts/local-validation/qa.sh test docs-index until the repository content passes.
5. Rebuild both Bazel docs targets and complete the browser checks in docs-build-render.md when content, navigation, configuration, assets, or MDX changed.

Boundary

This verifier proves index reachability, explicit sidebar resolution, configuration references, and common Markdown render invariants. It does not:

• compile MDX or execute Docusaurus plugins
• prove every maintained page is intentionally present in a sidebar
• verify labels, ordering, breadcrumbs, previous/next links, or visual layout
• load static assets in a browser
• prove deployed Cloudflare Pages behavior

Use the Bazel builds and the manual render checklist for those properties.