# Vitest Docs Guide

Guidance for working on the VitePress site in `docs/`. The root `AGENTS.md` applies here too.

## Building

- Local dev server: `pnpm docs` (from the repo root)
- Build with `pnpm docs:build` from the repo root; it sets the required env vars and regenerates the CLI table first
- The build type-checks code samples against the built workspace packages, so run `pnpm build` at the repo root first

## What fails the build

- Code blocks tagged `ts twoslash` are type-checked during `pnpm docs:build` only; the dev server skips twoslash and will not catch broken samples. A sample that intentionally fails needs `// @errors: <code>`; use `// ---cut---` and `// @filename:` to hide setup lines. Changing public types in `packages/` can break twoslash samples.
- Dead internal links fail the build. Every CLI option gets a generated link to `/config/<option>`, so a new option needs a matching `docs/config/<option>.md` page (or an entry in `skipConfig` in `docs/.vitepress/scripts/cli-generator.ts`).

## Conventions

- New docs pages are not auto-discovered: add a sidebar entry in `docs/.vitepress/config.ts` (the `/config`, `/guide`, and `/api` sidebars are hand-maintained arrays)
- Mark the version an API appeared in with `<Version>X.Y.Z</Version>` in the heading (the component renders the trailing `+` itself) plus an explicit `{#anchor}`
- Experimental APIs use `<Version type="experimental">X.Y.Z</Version>` with `<Experimental />`; deprecated APIs use `<Deprecated />`
- Config pages use frontmatter `title: <name> | Config`, `outline: deep`, and a `- **Type:** / - **Default:** / - **CLI:**` list

## Generated files (never edit by hand)

- `docs/guide/cli-generated.md` is generated from `packages/vitest/src/node/cli/cli-config.ts`; regenerate with `pnpm -C docs run cli-table` and commit the result
- `docs/.vitepress/contributor-names.json` is generated by `pnpm docs:contributors`