diff --git a/.changeset/add-mdx-content-components.md b/.changeset/add-mdx-content-components.md new file mode 100644 index 00000000..366d058e --- /dev/null +++ b/.changeset/add-mdx-content-components.md @@ -0,0 +1,5 @@ +--- +'@zpress/ui': minor +--- + +Add MDX content components for doc-platform parity: Accordion, AccordionGroup, Columns, Column, StatusBadge, Frame, Tooltip, Prompt, and Color. Reorganize theme barrel with public API sections and @internal annotations on framework exports. diff --git a/.gitignore b/.gitignore index 92886685..aaa8d1b2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ # Dependencies node_modules/ +# Superpowers brainstorm sessions +.superpowers/ + # Build output dist/ *.tsbuildinfo diff --git a/.joggr/.gg/.gitignore b/.joggr/.gg/.gitignore new file mode 100644 index 00000000..1bf3b502 --- /dev/null +++ b/.joggr/.gg/.gitignore @@ -0,0 +1,2 @@ +state.json +settings.local.json diff --git a/.joggr/.gg/README.md b/.joggr/.gg/README.md new file mode 100644 index 00000000..71894075 --- /dev/null +++ b/.joggr/.gg/README.md @@ -0,0 +1,104 @@ + + +# .joggr/.gg/ + +A structured workflow system for managing development projects through a phased pipeline. + +## Workflow Pipeline + +``` +/gg-new → /gg-discuss → /gg-research → /gg-plan → /gg-execute → /gg-verify +``` + +Each step advances the workflow. `.joggr/.gg/state.json` tracks only the active project. Phase status is tracked in phase file YAML frontmatter. + +## Skills + +Skills are slash commands that drive the workflow. Each skill manages state transitions, user interaction, and agent orchestration. + +| Skill | Description | +| ------------- | --------------------------------------------------------------------------------------------------------------- | +| `gg-new` | Scaffold a project from a Linear issue/project or free-text description | +| `gg-status` | Read-only tree view of project progress | +| `gg-discuss` | Interview user to gather requirements (goals, constraints, preferences, edge cases, acceptance criteria) | +| `gg-research` | Spawn background agent to explore codebase and web for technical context | +| `gg-plan` | Create phase plan with tasks, file targets, acceptance criteria, and dependencies | +| `gg-execute` | Group tasks into parallel waves and spawn executor agents | +| `gg-verify` | Spawn verifier agent to check acceptance criteria with concrete evidence | +| `gg-codebase` | Analyze repo and maintain `.joggr/.gg/codebase/` docs (stack, architecture, conventions, testing, integrations) | +| `gg-help` | Display all available commands and usage | + +## Agents + +Agents are subagents spawned by skills to do the actual work. + +| Agent | Interactive? | Description | +| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | +| `researcher` | No (background) | Codebase + web researcher — explores code, maps dependencies, finds existing patterns | +| `planner` | Yes | Task decomposer — breaks phases into tasks with file targets and acceptance criteria | +| `executor` | No (background) | Task implementer — executes one task, validates with typecheck/lint/test | +| `verifier` | No (background) | Acceptance verifier — checks every criterion with concrete evidence | +| `codebase-researcher` | No (background) | Codebase analyst — explores repo with Serena MCP tools, writes focused docs to `.joggr/.gg/codebase/` | + +## Docs + +Internal documentation for agent authors. + +| File | Purpose | +| ----------------------------- | --------------------------------------------------------------------- | +| `docs/core/architecture.md` | Overview, definitions, component interaction diagram | +| `docs/core/state.md` | State tracking, workflow artifacts, session persistence | +| `docs/standards/interface.md` | How skills pass context to agents and how agents return results | +| `docs/standards/agent.md` | Agent file structure, required/optional sections, example skeleton | +| `docs/standards/skill.md` | Skill file structure, common patterns, example skeleton | +| `docs/guides/linear.md` | Linear integration — ingestion, data flow, outcome vs. implementation | +| `docs/core/principles.md` | Behavioral principles for building skills and agents | + +## Troubleshooting + +If GG is behaving unexpectedly, see `TROUBLESHOOTING.md` in this directory for common failure modes and recovery steps. + +## Templates + +Templates scaffolded by `gg-new` into `.joggr/.gg/projects/{project-slug}/`. + +| File | Purpose | +| -------------------------- | ----------------------------------------------------- | +| `input.md` | Raw requirements and user intent | +| `discussion.md` | Timestamped interview log | +| `research.md` | Technical research findings | +| `overview.md` | Project overview and phase breakdown | +| `plan.md` | Project-level plan with phase/task XML | +| `phase.md` | Per-phase task plan with XML format | +| `codebase/stack.md` | Technology stack reference template | +| `codebase/architecture.md` | Architecture and structure reference template | +| `codebase/conventions.md` | Code conventions and style reference template | +| `codebase/testing.md` | Testing patterns and framework reference template | +| `codebase/integrations.md` | External integrations and services reference template | + +## Runtime Directory + +When a project is active, the working directory looks like: + +``` +.joggr/.gg/ +├── state.json # Workflow state +├── settings.json # GG configuration +├── settings.local.json # Local overrides (gitignored) +├── codebase/ # Shared codebase documentation +│ ├── stack.md +│ ├── architecture.md +│ ├── conventions.md +│ ├── testing.md +│ └── integrations.md +└── projects/ # All project directories + └── {project-slug}/ # Per-project directory + ├── input.md + ├── discussion.md + ├── research.md + ├── overview.md + ├── plan.md + └── phases/ + └── -/ + └── phase.md # Per-phase task plans +``` diff --git a/.joggr/.gg/TROUBLESHOOTING.md b/.joggr/.gg/TROUBLESHOOTING.md new file mode 100644 index 00000000..645bc267 --- /dev/null +++ b/.joggr/.gg/TROUBLESHOOTING.md @@ -0,0 +1,346 @@ + + +# GG Troubleshooting Guide + +Reference for diagnosing and recovering broken GG sessions. Covers the most common failure modes with concrete recovery steps. + +--- + +## Quick Diagnostic + +Run this first to understand the current state before doing anything else: + +```bash +# What project is active? +jog gg state get active_project + +# What's the phase status? +jog gg phase list {project-slug} + +# Is the working tree clean? +git status +``` + +--- + +## Common Failures + +### 1. Phase is stuck at `running` + +**Symptom:** A phase shows `step: execute, status: running` (or any step/running combination) but no agent is actively working. + +**Cause:** An executor agent was interrupted mid-session (crash, timeout, manual stop) without updating the phase file. + +**Fix:** + +```bash +# Reset phase back to the previous completed step +jog gg phase state {project-slug} {phase-number} --step execute --status error +``` + +Then re-run the skill that was in progress (e.g. `/gg-execute`). It will pick up from the last completed wave. + +If tasks were partially completed, check the phase file first: + +```bash +cat .joggr/.gg/projects/{project-slug}/phases/{N}-{slug}/phase.md +``` + +Mark completed tasks as `done` manually if needed, then re-run the skill. + +--- + +### 2. Agent spawned but did nothing + +**Symptom:** A skill says "Spawning researcher/executor/verifier agent..." but nothing happens, or the agent returns immediately without output. + +**Cause:** Usually one of: + +- Codebase docs missing (for research/plan/execute/verify) +- Agent hit a tool permission error +- Context window exceeded mid-session + +**Fix — check codebase docs first:** + +```bash +ls .joggr/.gg/codebase/*.md 2>/dev/null | head -1 +``` + +If empty → run `/gg-codebase` before retrying the skill. + +**Fix — retry the skill:** + +Re-run the skill. Background agents (researcher, executor, verifier) are stateless — retrying is always safe. + +--- + +### 3. Codebase docs are missing or stale + +**Symptom:** Skills stop at Step 0 with "Codebase docs not found. Run `/gg-codebase` first." + +**Or:** Research/plan output seems wrong for the current codebase state. + +**Fix:** + +```bash +# Regenerate codebase docs +/gg-codebase +``` + +This is safe to re-run at any time. It overwrites existing docs in `.joggr/.gg/codebase/`. + +--- + +### 4. Wrong project is active + +**Symptom:** A skill is operating on the wrong project, or you see "no active project" when you expect one. + +**Fix:** + +```bash +# See all projects +jog gg project list + +# Set the active project manually +jog gg state set active_project "{project-slug}" + +# Verify +jog gg state get active_project +``` + +--- + +### 5. Phase can't move forward (state machine error) + +**Symptom:** `jog gg phase state` fails with "Cannot move phase backward" or "Invalid step transition." + +**Cause:** The phase is already at or past the step you're trying to set. + +**Fix — check current phase status:** + +```bash +jog gg phase list {project-slug} +``` + +Phase steps move in order: `scaffold → discuss → research → plan → execute → verify`. You cannot go backward. If a phase needs to be re-done, manually edit the phase file frontmatter: + +```bash +# Edit the phase file directly +open .joggr/.gg/projects/{project-slug}/phases/{N}-{slug}/phase.md +``` + +Change `step` and `status` to the desired values, save, then re-run the skill. + +--- + +### 6. `state.json` is corrupted or missing + +**Symptom:** GG commands fail with JSON parse errors, or `jog gg state get` returns nothing. + +**Fix:** + +```bash +# Reset state to empty +echo '{"active_project":null}' > .joggr/.gg/state.json +``` + +Then set the active project again: + +```bash +jog gg state set active_project "{project-slug}" +``` + +--- + +### 7. Skills aren't showing up in Claude Code / Cursor + +**Symptom:** `/gg-new`, `/gg-plan`, etc. don't appear in the slash command menu. + +**Cause:** GG was not initialized, or skills were written to the wrong provider directory. + +**Fix:** + +```bash +# Re-run init to regenerate all skill files +jog init +``` + +Select "Set up guided workflows (GG)" and choose your provider. This regenerates all skill and agent files. + +Verify skills exist: + +```bash +ls ~/.claude/skills/gg-*/SKILL.md +``` + +--- + +### 8. An executor agent made incorrect changes + +**Symptom:** `/gg-execute` completed but the changes are wrong or broke something. + +**Fix — revert the wave:** + +```bash +# See checkpoint commits from this session +jog gg checkpoint log + +# Revert to before the bad wave +git revert HEAD~N # N = number of commits to undo +``` + +Then mark the affected tasks back to `todo` in the phase file, and re-run `/gg-execute`. + +--- + +### 9. Plan looks wrong after `/gg-plan` + +**Symptom:** The generated phase tasks don't match what you wanted, or phases are structured incorrectly. + +**Fix — re-plan:** + +Re-run `/gg-plan` on the same phase. The planner will re-read `discussion.md` and `research.md` and regenerate the plan. Existing phase files are overwritten. + +If the discussion itself is wrong, run `/gg-discuss` first to update it, then re-run `/gg-plan`. + +--- + +### 10. Phase stuck at `running` after cancelling `/gg-plan` + +**Symptom:** You cancelled `/gg-plan` mid-session (closed the terminal, hit escape, or chose "cancel" when the planner asked for approval). Now the phase shows `step: plan, status: running` and `/gg-plan` won't re-enter. + +**Cause:** The plan skill sets the phase to `running` before spawning the planner agent. If the session is cancelled before the planner finishes, the phase is never reset. + +**Fix:** + +```bash +jog gg phase state {project-slug} {phase-number} --step plan --status error +``` + +Then re-run `/gg-plan`. + +--- + +### 11. `/gg-discuss` ended too early + +**Symptom:** The discussion ended before you finished giving requirements. The skill exited after you said something like "move on" or "done with that" in a normal response, and now `discussion.md` is incomplete. + +**Cause:** The skill watches for exit signals in your responses ("enough", "move on", "done", "skip"). These words can appear in legitimate discussion responses and trigger an early exit. + +**Fix:** + +Re-run `/gg-discuss` on the same project. The skill appends to `discussion.md` — it will not overwrite previous entries. Just continue from where you left off. + +```bash +# Verify the current discussion state +cat .joggr/.gg/projects/{project-slug}/discussion.md +``` + +--- + +### 12. Research or codebase docs look empty or incomplete + +**Symptom:** `/gg-research` or `/gg-codebase` completed successfully, but when you read the output files they contain mostly template placeholders, section headers with no content, or very little actual information about the codebase. + +**Cause:** The agent wrote the file (passing validation) but didn't populate it with meaningful findings — usually because it couldn't find relevant code, hit a file limit, or the codebase docs were too sparse to work from. + +**Fix for research:** + +```bash +cat .joggr/.gg/projects/{project-slug}/research.md +``` + +If mostly empty, re-run `/gg-research`. Before retrying, make sure `/gg-codebase` has been run and the codebase docs have real content. + +**Fix for codebase docs:** + +```bash +ls -la .joggr/.gg/codebase/*.md +cat .joggr/.gg/codebase/stack.md +``` + +If files are tiny (< 1KB) or mostly headers, re-run `/gg-codebase`. You can optionally point it at a specific focus area (e.g., `tech`, `testing`) to get more targeted output. + +--- + +### 13. Wave aborted — partial commits left in repo + +**Symptom:** You chose "Abort phase" during `/gg-execute` after some tasks in a wave succeeded and were committed, but others failed. The phase is now at `error` but there are partial commits in your git history that don't represent a complete feature. + +**Fix — view what was committed:** + +```bash +jog gg checkpoint log +git log --oneline -10 +``` + +**Option A — keep the partial work and continue:** + +Fix the failed task manually, mark it done, and re-run `/gg-execute`: + +```bash +jog gg task set {project-slug} {phase-number} {task-id} --status done +jog gg phase state {project-slug} {phase-number} --step execute --status error +``` + +Then re-run `/gg-execute`. + +**Option B — revert the partial wave and start over:** + +```bash +# Revert N commits (N = number of checkpoint commits from the partial wave) +git revert HEAD~N --no-commit +git commit -m "revert: undo partial wave for {project-slug}" +``` + +Then reset task statuses back to `todo` and re-run `/gg-execute`. + +--- + +### 14. Task is stuck at `skip` but needs to be retried + +**Symptom:** A task was marked `skip` (either by you or automatically during a failed wave), but you want to run it now. `/gg-execute` skips over it because its status is `skip`. + +**Fix:** + +```bash +jog gg task set {project-slug} {phase-number} {task-id} --status todo +``` + +Then re-run `/gg-execute`. The task will be included in the next wave grouping. + +Verify the task ID first: + +```bash +jog gg phase get {project-slug} {phase-number} +``` + +--- + +## Manual State Recovery Reference + +| Problem | Command | +| -------------------- | ------------------------------------------------------------ | +| Check active project | `jog gg state get active_project` | +| Set active project | `jog gg state set active_project "{slug}"` | +| List all projects | `jog gg project list` | +| List phases + status | `jog gg phase list {slug}` | +| Reset a stuck phase | `jog gg phase state {slug} {N} --step {step} --status error` | +| Retry a skipped task | `jog gg task set {slug} {N} {task-id} --status todo` | +| View checkpoint log | `jog gg checkpoint log` | +| Squash checkpoints | `jog gg checkpoint squash "{message}"` | +| Check codebase docs | `ls .joggr/.gg/codebase/*.md` | +| Regenerate GG files | `jog init` → select GG setup | + +--- + +## When to Ask for Help + +If none of the above fixes work, the most useful context to share is: + +```bash +jog gg info +jog gg phase list {project-slug} +cat .joggr/.gg/projects/{project-slug}/phases/{N}-{slug}/phase.md +git log --oneline -10 +``` diff --git a/.joggr/.gg/settings.json b/.joggr/.gg/settings.json new file mode 100644 index 00000000..27cdfe3f --- /dev/null +++ b/.joggr/.gg/settings.json @@ -0,0 +1,27 @@ +{ + "schema": "1.0", + "applied_migrations": ["v1.0_01", "v1.0_02", "v1.0_03"], + "providers": ["claude-code", "cursor"], + "agents": { + "researcher": { + "mode": "teams", + "model": "opus" + }, + "codebase-researcher": { + "mode": "teams", + "model": "inherit" + }, + "planner": { + "mode": "foreground", + "model": "opus" + }, + "executor": { + "mode": "teams", + "model": "opus" + }, + "verifier": { + "mode": "teams", + "model": "inherit" + } + } +} diff --git a/.zpress/public/images/bunny.mp4 b/.zpress/public/images/bunny.mp4 new file mode 100644 index 00000000..0a4dd5b4 Binary files /dev/null and b/.zpress/public/images/bunny.mp4 differ diff --git a/.zpress/public/images/xkcd-automation.png b/.zpress/public/images/xkcd-automation.png new file mode 100644 index 00000000..1ef32f5f Binary files /dev/null and b/.zpress/public/images/xkcd-automation.png differ diff --git a/.zpress/public/images/xkcd-compiling.png b/.zpress/public/images/xkcd-compiling.png new file mode 100644 index 00000000..1577dcf3 Binary files /dev/null and b/.zpress/public/images/xkcd-compiling.png differ diff --git a/.zpress/public/images/xkcd-git.png b/.zpress/public/images/xkcd-git.png new file mode 100644 index 00000000..3f35d2d7 Binary files /dev/null and b/.zpress/public/images/xkcd-git.png differ diff --git a/docs/references/built-ins/accordion.mdx b/docs/references/built-ins/accordion.mdx new file mode 100644 index 00000000..e25a2fdd --- /dev/null +++ b/docs/references/built-ins/accordion.mdx @@ -0,0 +1,148 @@ +--- +title: Accordion +description: Expandable disclosure sections for progressive content reveal. +--- + +import { Accordion, AccordionGroup } from '@theme' + +# Accordion + +The `` component creates expandable sections with title, optional description and icon, URL-hash deep linking, and full keyboard accessibility. Built on `react-aria-components` for ARIA support. + +## Basic + +**Code** + +```mdx +import { Accordion } from '@theme' + + + +zpress is a documentation framework built on Rspress that generates +beautiful, themeable documentation sites from your codebase. + + +``` + +**Output** + + + +zpress is a documentation framework built on Rspress that generates +beautiful, themeable documentation sites from your codebase. + + + +## With description and icon + +**Code** + +````mdx + + +Run the following command to install zpress: + +```bash +pnpm add @zpress/kit +``` + + +```` + +**Output** + + + +Run `pnpm add @zpress/kit` to install. + + + +## Default open + +Use `defaultOpen` to start the accordion in the expanded state. + +**Code** + +```mdx + + +This content is visible on page load. + + +``` + +**Output** + + + +This content is visible on page load. + + + +## AccordionGroup + +Wrap multiple accordions in `` to coordinate them. Set `exclusive` so only one can be open at a time. + +**Code** + +```mdx +import { Accordion, AccordionGroup } from '@theme' + + + + Install the package with your preferred package manager. + + + Create a `zpress.config.ts` file in your project root. + + Run `pnpm build` to generate your documentation site. + +``` + +**Output** + + + + Install the package with your preferred package manager. + + + Create a `zpress.config.ts` file in your project root. + + Run `pnpm build` to generate your documentation site. + + +## Deep linking + +Each accordion generates a URL hash from its title (or custom `id` prop). Navigating to `#your-title` will auto-expand the matching accordion. + +```mdx + + Link to this section with `#my-custom-id`. + +``` + +## Accordion props + +| Prop | Type | Required | Default | Description | +| ------------- | ----------- | -------- | ------------- | ----------------------------------------- | +| `title` | `string` | yes | — | Title displayed in the trigger | +| `description` | `string` | no | — | Description below the title | +| `icon` | `string` | no | — | Iconify icon ID rendered before the title | +| `defaultOpen` | `boolean` | no | `false` | Whether to start expanded | +| `id` | `string` | no | slug of title | Custom anchor ID for deep linking | +| `children` | `ReactNode` | yes | — | Content revealed when expanded | + +## AccordionGroup props + +| Prop | Type | Required | Default | Description | +| ----------- | ----------- | -------- | ------- | ---------------------------------------- | +| `exclusive` | `boolean` | no | `false` | Only one accordion can be open at a time | +| `children` | `ReactNode` | yes | — | Accordion components to coordinate | diff --git a/docs/references/built-ins/color.mdx b/docs/references/built-ins/color.mdx new file mode 100644 index 00000000..99fd9d74 --- /dev/null +++ b/docs/references/built-ins/color.mdx @@ -0,0 +1,89 @@ +--- +title: Color +description: Color swatch display with click-to-copy. +--- + +import { Color, Columns, Column } from '@theme' + +# Color + +The `` component displays a color swatch with its value and an optional name. Click to copy the color value to your clipboard. + +## Basic + +**Code** + +```mdx +import { Color } from '@theme' + + + + +``` + +**Output** + + + + + +## With names + +**Code** + +```mdx + + + + + +``` + +**Output** + + + + + + + +## In a grid + +**Code** + +```mdx +import { Color, Columns, Column } from '@theme' + + + + + + + + + + + + +``` + +**Output** + + + + + + + + + + + + + +## Props + +| Prop | Type | Required | Default | Description | +| ------- | -------- | -------- | ------- | --------------------------- | +| `value` | `string` | yes | — | Color value (hex, rgb, hsl) | +| `name` | `string` | no | — | Display name for the color | diff --git a/docs/references/built-ins/columns.mdx b/docs/references/built-ins/columns.mdx new file mode 100644 index 00000000..fada411e --- /dev/null +++ b/docs/references/built-ins/columns.mdx @@ -0,0 +1,138 @@ +--- +title: Columns +description: Responsive grid layout for side-by-side content. +--- + +import { Columns, Column } from '@theme' + +# Columns + +The `` component arranges content in a responsive grid layout with 1–4 columns. Collapses to a single column on viewports below 640px. + +## Basic two-column layout + +**Code** + +````mdx +import { Columns, Column } from '@theme' + + + + +**Installation** + +```bash +pnpm add @zpress/kit +``` + + + + +**Usage** + +```bash +pnpm zpress build +``` + + + +```` + +**Output** + + + + +**Installation** + +Run `pnpm add @zpress/kit` + + + + +**Usage** + +Run `pnpm zpress build` + + + + +## Three columns + +**Code** + +```mdx + + + +### Fast + +Sub-second HMR with Rspress. + + + + +### Typed + +Zod-validated config with IntelliSense. + + + + +### Themed + +Three built-in themes, fully customizable. + + + +``` + +**Output** + + + + +### Fast + +Sub-second HMR with Rspress. + + + + +### Typed + +Zod-validated config with IntelliSense. + + + + +### Themed + +Three built-in themes, fully customizable. + + + + +## Four columns + +```mdx + + Column 1 + Column 2 + Column 3 + Column 4 + +``` + +## Columns props + +| Prop | Type | Required | Default | Description | +| ---------- | ------------------ | -------- | ------- | ---------------------------------------------- | +| `cols` | `1 \| 2 \| 3 \| 4` | no | `2` | Number of grid columns | +| `children` | `ReactNode` | yes | — | Grid content — raw children or Column wrappers | + +## Column props + +| Prop | Type | Required | Default | Description | +| ---------- | ----------- | -------- | ------- | ------------------------- | +| `children` | `ReactNode` | yes | — | Content for the grid cell | diff --git a/docs/references/built-ins/field.mdx b/docs/references/built-ins/field.mdx new file mode 100644 index 00000000..9f013846 --- /dev/null +++ b/docs/references/built-ins/field.mdx @@ -0,0 +1,264 @@ +--- +title: Field +description: Structured parameter and property documentation with type badges, status indicators, and nested grouping. +--- + +import { Field, FieldGroup } from '@theme' + +# Field + +The `` component documents a single parameter or property with a monospace name, type badge, required/optional/deprecated status, optional default value, and description body. Wrap related fields in `` to create titled sections, with optional collapsible behavior for nested objects and arrays. + +## Basic fields + +**Code** + +```mdx +import { Field, FieldGroup } from '@theme' + + + + The user's display name. + + + A valid email address used for login and notifications. + + + Short biography shown on the user's profile page. + + +``` + +**Output** + + + + The user's display name. + + + A valid email address used for login and notifications. + + + Short biography shown on the user's profile page. + + + +## Required and optional + +**Code** + +```mdx + + + The document title. Must be unique within the project. + + + Optional list of tags for categorization. + + +``` + +**Output** + + + + The document title. Must be unique within the project. + + + Optional list of tags for categorization. + + + +## With default values + +**Code** + +```mdx + + + Port number for the development server. + + + Theme identifier to apply to the documentation site. + + +``` + +**Output** + + + + Port number for the development server. + + + Theme identifier to apply to the documentation site. + + + +## Deprecated field + +**Code** + +```mdx + + + Use `outDir` instead. This field will be removed in v3. + + + Directory for build output. + + +``` + +**Output** + + + + Use `outDir` instead. This field will be removed in v3. + + + Directory for build output. + + + +## Nested object + +Use an expandable `` inside a `` to document object-typed properties. + +**Code** + +```mdx + + + Top-level configuration object. + + + Theme name to apply. + + + Dev server port. + + + + +``` + +**Output** + + + + Top-level configuration object. + + + Theme name to apply. + + + Dev server port. + + + + + +## Nested array + +For array types, nest a `` describing the shape of each array item. + +**Code** + +```mdx + + + List of matching user records. + + + Unique user identifier. + + + Display name. + + + Access level within the organization. + + + + +``` + +**Output** + + + + List of matching user records. + + + Unique user identifier. + + + Display name. + + + Access level within the organization. + + + + + +## CLI options + +`` also works well for documenting command-line flags. + +**Code** + +```mdx + + + Output directory for generated files. + + + Enable verbose logging output. + + + Path to a custom configuration file. + + +``` + +**Output** + + + + Output directory for generated files. + + + Enable verbose logging output. + + + Path to a custom configuration file. + + + +## Deep nesting + +:::tip +For objects nested deeper than two levels, consider linking to a dedicated reference page instead of inlining everything. Deeply nested expandable groups become hard to scan and navigate. +::: + +## Field props + +| Prop | Type | Required | Default | Description | +| -------------- | ----------- | -------- | ------- | ---------------------------------------------------------------- | +| `name` | `string` | yes | --- | Field name, rendered in monospace bold | +| `type` | `string` | no | --- | Type annotation shown as a pill badge | +| `required` | `boolean` | no | `false` | Shows a "required" badge instead of "optional" | +| `deprecated` | `boolean` | no | `false` | Shows a "deprecated" badge and strikes through the name | +| `defaultValue` | `string` | no | --- | Default value displayed below the header row | +| `children` | `ReactNode` | yes | --- | Description text and optional nested FieldGroup | + +## FieldGroup props + +| Prop | Type | Required | Default | Description | +| ------------- | ----------- | -------- | ------- | ---------------------------------------------------------- | +| `title` | `string` | yes | --- | Group label displayed as a header or collapsible trigger | +| `expandable` | `boolean` | no | `false` | Renders as a collapsible section with a toggle trigger | +| `defaultOpen` | `boolean` | no | `false` | Initial expanded state when `expandable` is true | +| `children` | `ReactNode` | yes | --- | Field children to display within the group | diff --git a/docs/references/built-ins/frame.mdx b/docs/references/built-ins/frame.mdx new file mode 100644 index 00000000..ffc69d06 --- /dev/null +++ b/docs/references/built-ins/frame.mdx @@ -0,0 +1,86 @@ +--- +title: Frame +description: Media wrapper for images and videos with captions. +--- + +import { Frame } from '@theme' + +# Frame + +The `` component wraps images and videos with consistent border styling, optional caption, and hint text. Uses semantic `
` / `
` HTML. + +## Basic image + +**Code** + +```mdx +import { Frame } from '@theme' + + + XKCD: Git + +``` + +**Output** + + + XKCD: Git + + +## With caption + +**Code** + +```mdx + + XKCD: Compiling + +``` + +**Output** + + + XKCD: Compiling + + +## With hint and caption + +**Code** + +```mdx + + XKCD: Automation + +``` + +**Output** + + + XKCD: Automation + + +## Video + +When a `