API reference panels

Document props, flags, endpoint fields, or config keys with the api tag and a YAML groups block.

The api tag renders a grouped reference panel in the same shell as tabs and code blocks: pill tabs with entry counts, one compact signature row per entry. Author groups as component YAML frontmatter so arrays, objects, and booleans reach the component as typed props. Signatures, counts, and badges all derive from that data.

content/docs/figure.md

::api
---
groups:
  - label: Props
    entries:
      - name: src
        annotation: asset
        required: true
        description: Image reference resolved by the content portability contract.
      - name: alt
        annotation: string
        required: true
        description: Alternative text announced by screen readers.
      - name: caption
        annotation: string
        optional: true
        description: Caption rendered below the image. The `default` slot replaces it with rich content.
      - name: zoom
        annotation: boolean | "auto"
        optional: true
        default: '"auto"'
        description: Opens the image in the zoom dialog on click.
  - label: Slots
    entries:
      - name: default
        description: Rich caption content, used instead of the `caption` prop.
---
::

This renders as:

src: asset required

Image reference resolved by the content portability contract.

alt: string required

Alternative text announced by screen readers.

caption?: string

Caption rendered below the image. The default slot replaces it with rich content.

zoom?: boolean | "auto" = "auto"

Opens the image in the zoom dialog on click.

Entry fields

Signatures are assembled mechanically from the entry fields: name + ? when optional + : annotation + = default. Never write a signature by hand.

Field	Type	Effect
`name`	string	Entry name. Required; entries without a name are dropped.
`annotation`	string	Type or signature, rendered in monospace after the name.
`optional`	boolean	Appends `?` to the name. Ignored when `required` is set.
`required`	boolean	Coral badge.
`deprecated`	boolean	Yellow badge and a struck-through name.
`since`	string	Mint badge, rendered as `since 2.1`.
`default`	string	Appended to the signature as `= value`.
`description`	string	One or two sentences below the signature. Backticks become code.

Header variants

The panel is data-agnostic: groups become tabs whether they hold component props, CLI flags, endpoint fields, or config keys. Two optional header forms give each data kind its identity. Use title with an optional icon for commands and files, or method with path for HTTP endpoints:

content/docs/http-example.md

::api{method="post" path="/api/feedback"}
---
groups:
  - label: Body
    entries:
      - name: page
        annotation: string
        required: true
        description: Route of the page the feedback refers to.
---
::

Deep links

Every entry row has a stable id of the form api-{group}-{name}, slugified. A link to #api-props-zoom activates the owning tab and scrolls to the row.

Keep API panels for structured reference sections. Use ordinary prose for a single narrated field.