mirror of
https://github.com/zoriya/v10.git
synced 2026-08-16 02:45:09 +00:00
72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# 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:`.
|
|
- Use arbitrary values only when no shared token fits and the exception is intentional.
|
|
- 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
|
|
|
|
- Docs and blog content use `.mdx`. Changelog entries under `src/content/changelog/` are generated `.md` files and are the exception.
|
|
- Blog filenames are `YYYY-MM-DD-slug.mdx`; `src/utils/globWithParser.ts` removes the date from the route slug.
|
|
- Use `FrameworkCase` and `StyleCase` for conditional guide content and keep `src/docs.config.ts` in sync.
|
|
- Use `<Aside>` for callouts. Do not add an H1 to content pages whose title comes from frontmatter.
|
|
- Add new guides to `src/docs.config.ts` and verify every supported framework/style route.
|
|
- Use `write-docs` or `review-docs` for prose workflows and `write-api-reference` for generated reference pages.
|
|
|
|
## 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.
|