Docs site maintenance

Local development

The Astro docs site shares the root package.json with the npm CLI package. Use docs-prefixed scripts:

npm run docs:dev

or with Bun:

bun run docs:dev

Astro usually serves the site at:

http://localhost:4321

Files to edit

src/data/docs.ts                site metadata, repo link, categories, nav
src/pages/index.astro           overview page
src/pages/docs/index.astro      grouped docs index
src/pages/docs/[...slug].astro  article route
src/pages/docs.md.ts            raw markdown index
src/pages/docs/[...slug].md.ts  raw markdown route
src/content/docs/*.md           docs pages
src/styles/global.css           visual system

Most content changes belong in src/content/docs.

Validate docs

npm run docs:check
npm run docs:build

or:

bun run docs:check
bun run docs:build

The docs build outputs static files to dist. Do not commit generated output.

Validate the CLI after docs changes

Docs-only changes should not affect the Go CLI or npm shim, but run the existing checks before pushing:

go test ./...
npm test

For broader maintainer confidence:

make check

npm package safety

The package files list controls what is included in the published npm package. The Astro source is not part of the CLI runtime path, so docs files can live in the repository without changing what the installed webctx command executes.