Skip to main content

Sync and verify

Every meaningful docs update should end with a repeatable verification pass. The commands below are the maintainer workflow for docs_ui.

Maintainer commands​

make sync
make dev
make build
make verify
make smoke

Raw pnpm equivalents:

pnpm sync-docs
pnpm sync-openapi
pnpm start:sync
pnpm build:sync
pnpm verify-docs
pnpm test:e2e

What each command proves​

  • make sync
    • regenerates imported markdown from scripts/doc-metadata.mjs
  • make dev
    • opens the local site on http://localhost:8877
  • make build
    • proves the production build still succeeds
  • make verify
    • runs lint, typecheck, tests, and build
  • make smoke
    • runs the end-to-end browser checks for search, routes, and rendered pages

For imported-doc changes:

make sync
make build

For curated content, nav, or project-metadata changes:

make sync
make dev
make verify

For route, search, or layout changes:

make sync
make verify
make smoke

Manual checks to do in the browser​

Open http://localhost:8877 and confirm:

  • the intended page appears in navigation
  • the project chip and Bitbucket link point to the right repo
  • search finds the page by the phrases people are likely to type
  • Mermaid diagrams still render in the current theme
  • mobile and desktop layouts still read cleanly

When to use Docker Compose​

If you need to verify the containerized site instead of the local dev server, run:

docker compose up --build -d

Then open http://localhost:8877.

Next steps​