API-Referenzpanels

Dokumentiere Props, Flags, Endpoint-Felder oder Config-Keys mit dem api-Tag und einem YAML-groups-Block.

Das api-Tag rendert ein gruppiertes Referenzpanel in derselben Hülle wie Tabs und Codeblöcke: Pill-Tabs mit Eintragszählern, eine kompakte Signaturzeile pro Eintrag. Verfasse groups als Komponenten-YAML-Frontmatter, damit Arrays, Objekte und boolesche Werte als typisierte Props bei der Komponente ankommen. Signaturen, Zähler und Badges leiten sich aus diesen Daten ab.

content/docs/figure.md

::api
---
groups:
  - label: Props
    entries:
      - name: src
        annotation: asset
        required: true
        description: Bildreferenz, aufgelöst über den Content-Portability-Vertrag.
      - name: alt
        annotation: string
        required: true
        description: Alternativtext für Screenreader.
      - name: caption
        annotation: string
        optional: true
        description: Bildunterschrift unter dem Bild. Der `default`-Slot ersetzt sie durch Rich Content.
      - name: zoom
        annotation: boolean | "auto"
        optional: true
        default: '"auto"'
        description: Öffnet das Bild per Klick im Zoom-Dialog.
  - label: Slots
    entries:
      - name: default
        description: Rich-Content-Bildunterschrift, verwendet statt der `caption`-Prop.
---
::

Das rendert als:

src: asset required

Bildreferenz, aufgelöst über den Content-Portability-Vertrag.

alt: string required

Alternativtext für Screenreader.

caption?: string

Bildunterschrift unter dem Bild. Der default-Slot ersetzt sie durch Rich Content.

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

Öffnet das Bild per Klick im Zoom-Dialog.

Eintragsfelder

Signaturen entstehen mechanisch aus den Eintragsfeldern: name + ? bei optional + : annotation + = default. Schreibe Signaturen nie von Hand.

Feld	Typ	Wirkung
`name`	string	Name des Eintrags. Pflicht; Einträge ohne Namen werden verworfen.
`annotation`	string	Typ oder Signatur, in Monospace hinter dem Namen.
`optional`	boolean	Hängt `?` an den Namen an. Wird bei gesetztem `required` ignoriert.
`required`	boolean	Korallenrotes Badge.
`deprecated`	boolean	Gelbes Badge und durchgestrichener Name.
`since`	string	Mintfarbenes Badge, gerendert als `since 2.1`.
`default`	string	Wird als `= wert` an die Signatur angehängt.
`description`	string	Ein bis zwei Sätze unter der Signatur. Backticks werden zu Code.

Header-Varianten

Das Panel ist datenagnostisch: Gruppen werden zu Tabs, egal ob sie Komponenten-Props, CLI-Flags, Endpoint-Felder oder Config-Keys enthalten. Zwei optionale Header-Formen geben jeder Datenart ihre Identität. Verwende title mit optionalem icon für Befehle und Dateien oder method mit path für HTTP-Endpoints:

content/docs/http-beispiel.md

::api{method="post" path="/api/feedback"}
---
groups:
  - label: Body
    entries:
      - name: page
        annotation: string
        required: true
        description: Route der Seite, auf die sich das Feedback bezieht.
---
::

Deep Links

Jede Eintragszeile hat eine stabile ID der Form api-{gruppe}-{name}, verslugt. Ein Link auf #api-props-zoom aktiviert den zugehörigen Tab und scrollt zur Zeile.

Verwende API-Panels für strukturierte Referenzabschnitte. Nutze gewöhnliche Prosa für ein einzelnes beschriebenes Feld.