API reference
Treat TypeScript source and the builder E2E test as the specification. Generated JSON is diagnostic output, not an editable source.
Workflow
- Identify the export and read its implementation, public export path, tests, and any matching design record.
- Read
site/scripts/api-docs-builder/src/tests/e2e.test.ts to confirm the builder contract involved in the change.
- Load only the needed reference:
- Component discovery or naming failure:
references/builder-conventions.md
- Hook, controller, mixin, factory, or other utility:
references/util-conventions.md
- New MDX reference page:
references/mdx-structure.md
- New interactive example:
references/demo-patterns.md
- Run
pnpm -F site api-docs and inspect the corresponding file under site/src/content/generated-*-reference/.
- Fix missing metadata at the TypeScript/JSDoc source or in the builder. Do not hand-edit generated JSON.
- Create or update
site/src/content/docs/reference/<slug>.mdx and the matching site/src/docs.config.ts entry when a page is required.
- Verify the page for every supported framework/style combination it targets.
Component pages
- Derive props, state, data attributes, parts, tag names, and behavior from source.
- Add prose only for non-obvious behavior, styling contracts, accessibility, or platform constraints.
- Keep reference prose neutral and descriptive: state facts, let examples illustrate without teaching, and link how-to guides for tasks and concept pages for rationale (see
.agents/skills/write-docs/references/diataxis.md).
- Include basic HTML and React demos when both platforms expose the component; follow existing neighboring demos when the reference guide leaves room for judgment.
Utility pages
- Confirm the export is reachable from a builder-scanned public entry point.
- Add
@public only when the export intentionally belongs in reference docs and naming-based discovery does not include it.
- Verify generated overloads, parameters, and return data before authoring prose.
Validation
Run the builder E2E test for builder changes, pnpm -F site api-docs, and the narrowest site check that renders the affected page.
Example
Input: “Add the Menu component API reference.”
Output: Source JSDoc and builder-compatible metadata, verified generated output, MDX examples, navigation config, and site checks.
1---2name: write-api-reference3description: Write generated Video.js API reference pages. Use for components, hooks, controllers, factories, builder compatibility, demos, or extracted JSDoc.4---56# API reference78Treat TypeScript source and the builder E2E test as the specification. Generated JSON is diagnostic output, not an editable source.910## Workflow11121. Identify the export and read its implementation, public export path, tests, and any matching design record.132. Read `site/scripts/api-docs-builder/src/tests/e2e.test.ts` to confirm the builder contract involved in the change.143. Load only the needed reference:15 - Component discovery or naming failure: `references/builder-conventions.md`16 - Hook, controller, mixin, factory, or other utility: `references/util-conventions.md`17 - New MDX reference page: `references/mdx-structure.md`18 - New interactive example: `references/demo-patterns.md`194. Run `pnpm -F site api-docs` and inspect the corresponding file under `site/src/content/generated-*-reference/`.205. Fix missing metadata at the TypeScript/JSDoc source or in the builder. Do not hand-edit generated JSON.216. Create or update `site/src/content/docs/reference/<slug>.mdx` and the matching `site/src/docs.config.ts` entry when a page is required.227. Verify the page for every supported framework/style combination it targets.2324## Component pages2526- Derive props, state, data attributes, parts, tag names, and behavior from source.27- Add prose only for non-obvious behavior, styling contracts, accessibility, or platform constraints.28- Keep reference prose neutral and descriptive: state facts, let examples illustrate without teaching, and link how-to guides for tasks and concept pages for rationale (see `.agents/skills/write-docs/references/diataxis.md`).29- Include basic HTML and React demos when both platforms expose the component; follow existing neighboring demos when the reference guide leaves room for judgment.3031## Utility pages3233- Confirm the export is reachable from a builder-scanned public entry point.34- Add `@public` only when the export intentionally belongs in reference docs and naming-based discovery does not include it.35- Verify generated overloads, parameters, and return data before authoring prose.3637## Validation3839Run the builder E2E test for builder changes, `pnpm -F site api-docs`, and the narrowest site check that renders the affected page.4041## Example4243Input: “Add the Menu component API reference.”4445Output: Source JSDoc and builder-compatible metadata, verified generated output, MDX examples, navigation config, and site checks.
videojs