v10/site/scripts/api-docs-builder

API Docs Builder

Generates API reference JSON from TypeScript sources for Video.js 10 components and utilities.

Spec: internal/design/site/api-docs-builder.md is the ground-truth for discovery conventions, extraction rules, JSON schemas, the reference model, and rendered output. When implementation diverges from the spec, the spec wins.

Architecture

TypeScript Sources (core/html/react/store packages)
         ↓
   api-docs-builder (typescript-api-extractor)
         ↓
   JSON files (component + util references)
         ↓
   Astro components (ComponentReference / UtilReference)
         ↓
   Interactive tables in MDX pages

Usage

Building

The builder runs automatically before dev/build via npm scripts:

# Run manually
pnpm api-docs

# Runs automatically on:
pnpm dev      # via predev hook
pnpm build    # via prebuild hook

In MDX

import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
import UtilReference from "@/components/docs/api-reference/UtilReference.astro";

<ComponentReference component="PlayButton" />
<UtilReference util="usePlayer" />

File Structure

site/scripts/api-docs-builder/
├── README.md                  # This file
└── src/
    ├── index.ts               # Main entry point, orchestrates handlers
    ├── types.ts               # TypeScript interfaces
    ├── formatter.ts           # Type formatting utilities
    ├── utils.ts               # Utility functions (naming helpers)
    ├── core-handler.ts        # Extracts Props/State from core packages
    ├── data-attrs-handler.ts  # Extracts data attributes
    ├── html-handler.ts        # Extracts Lit element info
    ├── parts-handler.ts       # Parses index.parts.ts for multi-part components
    ├── util-handler.ts        # Extracts util params/return from store/react packages
    └── tests/
        ├── test-utils.ts
        ├── fixtures/          # Monorepo fixtures for integration tests
        ├── core-handler.test.ts
        ├── data-attrs-handler.test.ts
        ├── formatter.test.ts
        ├── html-handler.test.ts
        ├── parts-handler.test.ts
        ├── util-handler.test.ts
        └── utils.test.ts

site/src/
├── content/generated-component-reference/  # Generated component JSON (gitignored)
├── content/generated-util-reference/       # Generated util JSON (gitignored)
└── components/docs/api-reference/
    ├── ComponentReference.astro  # Renders full component API reference
    ├── UtilReference.astro       # Renders full util API reference
    ├── ApiPropsTable.astro       # Props table
    ├── ApiStateTable.astro       # State interface table
    ├── ApiDataAttrsTable.astro   # Data attributes table
    ├── UtilParamsTable.astro     # Util parameters table
    ├── UtilReturnTable.astro     # Util return type table
    ├── PropRow.astro             # Expandable prop row
    ├── StateRow.astro            # Expandable state row
    ├── DataAttrRow.astro         # Data attribute row
    ├── DetailRow.astro           # Shared disclosure row
    └── InlineMarkdown.astro      # Renders inline markdown (backticks → <code>)

Dependencies

• typescript-api-extractor: AST parsing for TypeScript types
• es-toolkit: Utility functions (kebabCase, etc.)
• tsx: TypeScript execution

All dependencies are in site/package.json devDependencies.

Acknowledgements

This builder's architecture and approach were inspired by Base UI's api-docs-builder, maintained by MUI. Base UI is licensed under the MIT License (Copyright 2019 Material-UI SAS). Thank you to the MUI team for the excellent reference implementation.