Type to search.

↵ to open ↑↓ to navigate Esc to close

API reference style

Two pieces of markup turn an ordinary article into an API reference page: <section class="api"> for methods, endpoints, or components, and <dt class="api"> for the options under them. Both render with a monospace heading and both feed the client-side symbol search index.

API sections

Adding class="api" to a <section> draws a rule above it and renders its heading in the monospace family at a semi-bold weight. Use it for each addressable unit of the API — a function, a class, an endpoint, a CLI subcommand: 

<section class="api">
  <h3 id="processOrder">processOrder(order, options)</h3>
  <p>Validates and enqueues an order for fulfillment.</p>
</section>

The same markup, rendered:

processOrder(order, options)

Validates the order, computes totals, and enqueues it for fulfillment. Returns a promise that resolves to the persisted order record. Throws ValidationError if the order fails validation before enqueue.

cancelOrder(orderId)

Marks an order as cancelled and emits a order.cancelled event. Idempotent — calling it again on an already-cancelled order is a no-op.

Option lists

Inside an API section, a definition list with dt.api terms documents the options. Each term renders in monospace, matching the heading style.

Options

notify

When true, sends a confirmation email after the order is persisted. Defaults to true outside of test runs.

idempotencyKey

A client-supplied key used to de-duplicate retried requests. Required when the call is made from a worker that may be replayed.

dryRun

When true, runs validation and pricing but doesn’t enqueue the order. Useful for previewing totals before commit.

Markers

Two presentational classes annotate entries without adding markup noise — the labels are generated from CSS, so the source stays clean.

Add required to a dt.api term to append a muted (required) suffix: 

<dt class="api required" id="idempotencyKey">idempotencyKey</dt>
idempotencyKey

The same option, marked required — the suffix is added by the stylesheet.

Add read-only to a section.api to float a [read-only] marker into the article’s right gutter: 

<section class="api read-only">
  <h3 id="createdAt">createdAt</h3>
</section>

createdAt

Timestamp set when the record is created and never changed afterward. The [read-only] marker sits in the right gutter.

The symbol index

Every .api element is harvested at build time into symbols.json at the site root. The Web Component that powers symbol search lazy-loads that manifest the first time you press / and queries it through fuzzysort. See Search → API symbols for the runtime side.

Each harvested entry looks like:

{
  "name": "processOrder(order, options)",
  "kind": "method",
  "url": "/api-reference/",
  "anchor": "processOrder"
}

name

The display string. By default the extractor reads the <h*> text for sections and the <dt> text for options. Override it with data-api-name when the rendered text isn’t the searchable identifier — for instance when you want processOrder() on screen but processOrder in the index. 

<section class="api">
  <h3 id="processOrder"
      data-api-name="processOrder">processOrder(order, options)</h3>
</section>

kind

A short label rendered next to the entry in the search results. Inferred by default: option for <dt class="api">, and for <section class="api"> either method when the name ends in (…) or property otherwise. Override with data-api-kind when you want a more specific label: 

<section class="api" data-api-kind="endpoint">
  <h3 id="getUsers">GET /users</h3>
</section>

Common values are method, endpoint, event, option, flag.

anchor

The fragment used in the deep link. Comes from the element’s own id, falling back to the section’s first heading id, falling back to the nearest ancestor with an id. The extractor warns if it can’t find an anchor — symbols without one are unreachable from the index.

Putting it together

A complete API page typically alternates section headings with their option lists. Here’s a compact endpoint reference for two operations, covering limit, cursor, status, id, and include:

GET /users

Returns a paginated list of users. Results are sorted by creation time, newest first.

limit

Page size, 1–100. Default 20.

cursor

Opaque pagination token from a previous response’s next field.

status

Filter by status: active, pending, or archived. Omit to include all.

GET /users/:id

Returns a single user by id, including inline organization details.

id

The user’s unique identifier.

include

Comma-separated list of expansions: organization, permissions, activity.