API Fields

The built-in field tag — hand-authored API parameter and response-field rows for references that aren't driven by an OpenAPI spec. One tag renders a labeled row: the field name, its type, required/deprecated badges, an optional default, an optional request-location badge, and a Markdown description. Usage, options, and live examples.

A built-in tag for documenting an API by hand — when there is no OpenAPI spec driving the page. {% field %} renders one labeled row: the field name (monospace), its type, required / deprecated badges, an optional default, an optional location badge (query / path / body / header / cookie), and a Markdown description written as the block body.

One tag covers both request parameters and response fields, because the two render identically. The only request-only affordance is the location badge — and a response field, being just a key in the returned payload, simply omits it.

This is for prose you write yourself. If you already have an OpenAPI spec, reach for OpenAPI instead — it renders parameter and response tables straight from the spec, with a “Try it now” form. field is the spec-free counterpart: drop one row at a time into a guide.

Use it as {% field %} in Markdown, or call it from Python logic (loops, snippets) via component('aardvark', 'field', …).

What location means

location is the one attribute that makes a row a request parameter. It answers the question a name and a type can’t: where does this value go in the HTTP request?

It is the hand-authored mirror of OpenAPI’s in field: a field with location="query" renders exactly what {% openapi %} shows for in: query. A response field has no request location, so you just leave location off.

Request parameters

{% field %} takes the field name (the only required attribute), an optional type, the required and deprecated flags, an optional default, and an optional location. The block body is the description — full Markdown. Close it with {% endField %}.

Response fields

A response field is the same tag with no location — there is nowhere in a request for it to go. Everything else works identically.

Request vs response fields

One tag serves both. A request parameter carries a location (query, path, body, header, or cookie — OpenAPI’s in, where the value rides in the request); a response field is just a key in the returned payload, so it omits location and shows no location badge. Nothing else differs — the two render identically.

{% field name="petId" type="integer" required=true location="path" %}
A request parameter — the `location` badge marks where it rides.
{% endField %}

{% field name="id" type="string" %}
A response field — no location, no badge.
{% endField %}

Rich descriptions

The body is full Markdown, so a field description can hold emphasis, links, inline code, and lists — handy for enumerating allowed values or nested shapes:

Attributes

CSS Selectors

Every row renders the same ApiField island, so one wrapper class targets them all.

[data-aardvark-island="ApiField"] {
  /* style every field row on the page */
}

[data-aardvark-island="ApiField"] .aardvark-api-field-name {
  /* the monospace field name */
}

[data-aardvark-island="ApiField"] .aardvark-api-field-body {
  /* the Markdown description */
}

Injecting Attributes

attr={…} forwards raw HTML attributes (including an id for deep-linking) straight onto the rendered field row.