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