Skip to content

mdx-structure.md

Latest commit

 

History

History
336 lines (245 loc) · 8.1 KB

mdx-structure.md

File metadata and controls

336 lines (245 loc) · 8.1 KB

MDX Structure

Structure and conventions for API reference MDX pages at site/src/content/docs/reference/.

Component Pages

Frontmatter

---
title: MuteButton              # PascalCase component name
frameworkTitle:
  html: media-mute-button      # HTML custom element tag name
description: A button component for muting and unmuting audio playback
---
  • title: PascalCase React component name
  • frameworkTitle.html: The static tagName from the HTML element file
  • description: One-line description of the component

Page Structure

frontmatter
imports (React demos, HTML demos)
## Anatomy
## Behavior       (if applicable)
## Styling        (if applicable)
## Accessibility  (if applicable)
## Examples
### BasicUsage
### [Additional demos]
<ComponentReference component="{PascalCase}" />

Imports Section

React demo imports

{/* React demos */}
import BasicUsageDemoReact from "@/components/docs/demos/{component}/react/css/BasicUsage";
import basicUsageReactTsx from "@/components/docs/demos/{component}/react/css/BasicUsage.tsx?raw";
import basicUsageReactCss from "@/components/docs/demos/{component}/react/css/BasicUsage.css?raw";
  • Component import: default export from .tsx (no extension needed)
  • Source imports: ?raw suffix for displaying source code in tabs

HTML demo imports

{/* HTML demos */}
import BasicUsageDemoHtml from "@/components/docs/demos/{component}/html/css/BasicUsage.astro";
import basicUsageHtml from "@/components/docs/demos/{component}/html/css/BasicUsage.html?raw";
import basicUsageHtmlCss from "@/components/docs/demos/{component}/html/css/BasicUsage.css?raw";
import basicUsageHtmlTs from "@/components/docs/demos/{component}/html/css/BasicUsage.ts?raw";
  • .astro wrapper: renders live demo
  • .html, .css, .ts: ?raw imports for source tabs

Import naming convention

Type Pattern Example
React component {DemoName}DemoReact BasicUsageDemoReact
React source {demoName}React{Ext} basicUsageReactTsx
HTML component {DemoName}DemoHtml BasicUsageDemoHtml
HTML source {demoName}Html / {demoName}Html{Ext} basicUsageHtml, basicUsageHtmlCss

Anatomy Section

## Anatomy

<FrameworkCase frameworks={["react"]}>
```tsx
<MuteButton />

<FrameworkCase frameworks={["html"]}>

<media-mute-button></media-mute-button>
```

For multi-part components, show composed usage:

<FrameworkCase frameworks={["react"]}>
```tsx
<Time.Group>
  <Time.Value type="current" />
  <Time.Separator />
  <Time.Value type="duration" />
</Time.Group>
```

Prose Sections

Behavior

Explain state transitions, timing, and interaction logic. Use tables for enumerated states:

## Behavior

Toggles mute on and off. Exposes a derived `volumeLevel` based on the current volume and mute state:

| Level | Condition |
|-------|-----------|
| `off` | Muted or volume is 0 |
| `low` | Volume < 0.5 |

Styling

Show data attributes as a table, then CSS selector patterns:

## Styling

| Attribute | Values | Description |
|-----------|--------|-------------|
| `data-muted` | Present / absent | Present when audio is muted |
| `data-volume-level` | `"off"` \| `"low"` \| `"medium"` \| `"high"` | Current volume level |

Use `data-volume-level` for multi-level icon switching:

```css
media-mute-button[data-volume-level="off"] .icon-off { display: inline; }

### Accessibility

Describe ARIA attributes, keyboard interactions, and label overrides:

```mdx
## Accessibility

Renders a `<button>` with an automatic `aria-label`: "Unmute" when muted, "Mute" when unmuted. Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.

Examples Section

Nesting pattern

## Examples

### Basic Usage

<FrameworkCase frameworks={["react"]}>
  <StyleCase styles={["css"]}>
    <Demo files={[
      { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
      { title: "App.css", code: basicUsageReactCss, lang: "css" },
    ]}>
      <BasicUsageDemoReact client:idle />
    </Demo>
  </StyleCase>
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
  <StyleCase styles={["css"]}>
    <Demo files={[
      { title: "index.html", code: basicUsageHtml, lang: "html" },
      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
    ]}>
      <BasicUsageDemoHtml />
    </Demo>
  </StyleCase>
</FrameworkCase>

Key details:

  • React demos use client:idle for hydration
  • HTML demos render server-side (no client:* directive)
  • React source tabs: App.tsx, App.css
  • HTML source tabs: index.html, index.css, index.ts

ComponentReference Component

Always the last element in the file:

<ComponentReference component="MuteButton" />

The component auto-renders Props, State, Data Attributes, and CSS Custom Properties for single-part and all Parts for multi-part. For multi-part components, React-only parts are hidden in HTML docs via framework filtering.

Required Astro Component Imports

Every component reference MDX needs these at the top of the imports:

import ComponentReference from "@/components/docs/api-reference/ComponentReference.astro";
import FrameworkCase from "@/components/docs/FrameworkCase.astro";
import StyleCase from "@/components/docs/StyleCase.astro";
import Demo from "@/components/docs/demos/Demo.astro";

Cross-linking

Link generously between related reference pages.

Same-framework or cross-framework link:

Within a player provider, <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> is usually simpler.

Selector page linking to framework-specific utils:

<FrameworkCase frameworks={["react"]}>
Pass `selectPlayback` to <DocsLink slug="reference/use-player">`usePlayer`</DocsLink> to subscribe.
</FrameworkCase>

<FrameworkCase frameworks={["html"]}>
Pass `selectPlayback` to <DocsLink slug="reference/player-controller">`PlayerController`</DocsLink> to subscribe.
</FrameworkCase>

Util Pages

Util pages document React hooks/utilities and HTML controllers/mixins. They are simpler than component pages — no demos, no anatomy.

Frontmatter

---
title: usePlayer
description: Hook to access the player store from within a Player Provider
---
  • title: The exported function/class name (e.g., usePlayer, PlayerController)
  • No frameworkTitle — util pages are framework-specific
  • description: One-line description

Page Structure

frontmatter
import UtilReference
## Import
## Usage
<UtilReference util="{Name}" />

Import Section

Show the import statement for the util:

## Import

\`\`\`tsx
import { usePlayer } from '@videojs/react';
\`\`\`

Usage Section

Explain usage patterns with code examples. For multi-overload utils, document each overload:

## Usage

`usePlayer` has two overloads:

**Store access (no subscription)** -- returns the store instance.

\`\`\`tsx
const store = usePlayer();
\`\`\`

**Selector-based subscription** -- returns selected state.

\`\`\`tsx
const paused = usePlayer((s) => s.paused);
\`\`\`

UtilReference Component

Always the last element in the file:

<UtilReference util="usePlayer" />

The component auto-renders Parameters and Return Value tables. For multi-overload utils, it renders each overload with its own sections.

Required Import

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

Sidebar Entry

Add to site/src/docs.config.ts in the appropriate section, alphabetically:

  • Components — UI component reference pages
  • Hooks & Utilities (frameworks: ['react']) — React hooks and utilities
  • Controllers & Mixins (frameworks: ['html']) — HTML controllers and mixins
{
  sidebarLabel: 'Components',
  contents: [
    // sorted alphabetically
    { slug: 'reference/buffering-indicator' },
    { slug: 'reference/controls' },
    // ...
    { slug: 'reference/{name}' },  // <-- insert alphabetically
    // ...
  ],
},