API reference recipe
Rendered
Goal
When a developer lands on an endpoint page, they need three things at once: (1) what the endpoint does, (2) what to send and what comes back, (3) a way to try it without leaving the page. The API-reference recipe puts all three in front of them without scrolling.
Layout breakdown
Two-column body inside a docs-shell topbar + sidebar. Region map:
┌─ Topbar (global) ──────────────────────────────────────────────┐
│ [Matter logo] Docs Brand API Changelog [Try] ⌘K │
├─ Sidebar ─┬─ Operation column (8/12) ──┬─ TOC rail (4/12) ─────┤
│ Create │ ◇ Eyebrow │ On this page │
│ Manage │ EndpointBadge + Path │ • Request │
│ Exit │ Description (3 paragraphs) │ • Response │
│ Tokens │ CodeBlock w/ EndpointBadge │ • Errors │
│ … │ header — request │ • SDK example │
│ │ CodeBlock w/ EndpointBadge │ • Webhook │
│ │ header — response (200) │ │
│ │ Tabs (Errors / Webhooks) │ │
│ │ │ │
└───────────┴─────────────────────────────┴───────────────────────┘The operation column is 8/12 columns at desktop, full-width on mobile. The TOC rail collapses below the operation column at < 1024px.
Component manifest
| Region | Component | Why over alternatives |
|---|---|---|
| Topbar | AppBreadcrumb + global nav | Breadcrumb anchors the user's place in the API tree; global nav stays sticky |
| Sidebar | Fumadocs <DocsLayout sidebar> | Native to the docs framework; preserves search + collapsible groups |
| Operation eyebrow | Eyebrow | Section anchor — "Create" / "Manage" / "Exit" lifecycle phase |
| Endpoint header | EndpointBadge | Method-color chip + path; reads at a glance |
| Code surfaces | CodeBlock with header slot | The V2 canonical shape — header carries EndpointBadge + latency |
| Try-it-now | Scalar playground (embedded iframe) | Inline execution without leaving the page |
| TOC rail | Fumadocs <DocsPage toc> | Native; auto-derived from heading hierarchy |
Responsive behaviour
| Breakpoint | Operation column | TOC rail |
|---|---|---|
< 768px | Full width; sidebar drawer | Hidden (TOC accessible via top button) |
768–1023px | Full width | Below operation column |
≥ 1024px | 8/12 cols | 4/12 cols, sticky |
States
| State | Trigger | Behaviour |
|---|---|---|
| Default | Page load | Operation column hydrates first, playground iframe lazy-loads |
| Playground loading | Scalar embed initialising | Skeleton placeholder; non-blocking |
| Try-it executed | User clicks Run | Response area updates with latency + body; CodeBlock header shows real status |
| Error | Scalar request fails | Inline error message in the response CodeBlock; preserve request body |
| Mobile | < 768px | Sidebar collapses to drawer; TOC moves to top-button menu |
Implementation
Source: apps/docs/app/(docs)/[...slug]/page.tsx. The route handler reads the OpenAPI operation from apps/docs/api-reference/openapi.yaml, hydrates it through the generated MDX, and renders the operation column. The Scalar playground iframe lives in a sibling apps/docs/components/scalar-playground.tsx and is mounted as a next/dynamic import (no SSR).