# Video.js site guide

This file contains site-specific gotchas. Read `site/README.md`, `site/package.json`, the relevant implementation, and its tests for the current architecture and commands.

## Sources of truth

- Commands and versions: `package.json`
- Astro/Vite/Markdown configuration: `astro.config.mjs`
- Content schemas: `src/content.config.ts`
- Framework/style support and type guards: `src/types/docs.ts`
- Sidebar and route availability: `src/docs.config.ts`
- Design tokens and variants: `src/styles/globals.css`
- Guide authoring: `src/content/docs/how-to/write-guides.mdx`
- API builder contract: `scripts/api-docs-builder/src/tests/e2e.test.ts`
- Deployment workflow: root `.github/workflows/`

If this guide conflicts with those files, use the executable source and update this guide.

## Commands

From the repository root:

```bash
pnpm dev:site
pnpm build:site
pnpm -F site test [path-or-pattern]
pnpm -F site api-docs
pnpm -F site astro check
```

## Styling and components

- Inspect `src/styles/globals.css` before choosing Tailwind classes. Prefer existing theme tokens and semantic utilities.
- Use the custom `intent:` variant for pointer/focus intent where existing site code does; do not replace it mechanically with `hover:`.
- Prefer a token-based utility when one fits. For a non-token one-off, use an inline style instead of an arbitrary-value class such as `min-h-[120px]`.
- When a non-token value needs a responsive, dark-mode, or other Tailwind variant, bridge it through an inline CSS custom property, for example `style="--md-min-h: 120px"` with `class="md:min-h-(--md-min-h)"`.
- Use `clsx` in React and `class:list` in Astro for conditional classes.
- React islands are independent roots. Use Nanostores for cross-island state instead of React context.
- React Compiler is enabled; do not add memoization without a measured or documented need.

## Content

- Read `src/content/docs/how-to/write-guides.mdx` before adding or reviewing site prose. It owns document types, frontmatter, sidebar registration, framework/style variants, voice, and MDX conventions.
- Changelog source format and generation are owned by `src/content.config.ts` and the root changelog workflows; follow those sources rather than duplicating their extension rules here.
- Blog filenames are `YYYY-MM-DD-slug.mdx`; `src/utils/globWithParser.ts` removes the date from the route slug.
- Use `write-docs` or `review-docs` for prose workflows and `write-api-reference` for generated reference pages.

## Demos

- Use `{{VJS*}}` placeholders from `scripts/replace-demo-placeholders.ts` for shared media URLs in HTML and React demos.
- Keep demo-specific CSS scoped under a unique root class.
- Prefix demo classes with framework, component, and variant.
- Reflect meaningful HTML demo state to `data-*` attributes and style those attributes.
- Use React state for React demo rendering; avoid querying the DOM for application state.
- Set explicit media attributes needed by the scenario (`muted`, `playsinline`, `crossorigin`, and preload behavior).

## Site-specific gotchas

- `astro.config.mjs` has a root `vite.optimizeDeps` block that can shadow renderer-provided includes. Keep React client dependencies in its explicit `include` list when changing renderer setup.
- Markdown uses Satteri MDAST plugins, not remark/rehype plugins. Add transformations with `defineMdastPlugin` and write derived frontmatter through `ctx.data.astro.frontmatter`.
- Shiki highlighting is configured independently from the Markdown processor.
- React context does not cross Astro islands.
- Never expose `context.locals.accessToken` to client code. Auth and Mux integration are only for the installation uploader; trace the middleware and server actions before changing that flow.

## API references

Generated reference JSON is gitignored and rebuilt by `pnpm -F site api-docs`, dev, and build. Do not hand-edit it. Change the TypeScript/JSDoc input or the builder, run the generator, and inspect the output. Keep the builder E2E suite passing.

## Verification

Run the narrowest unit tests while iterating. For content or UI work, verify affected framework/style variants in the browser. For builder changes, run its E2E test plus `pnpm -F site api-docs`. Finish with `pnpm -F site astro check` or the relevant site build when the change affects compilation.