write-api-reference

Writing API Reference Pages

Goal

Produce an API reference page that documents a single API surface (function, component, file convention, directive, or config option). The page should be concise, scannable, and example-driven.

Each page documents one API. If the API has sub-methods (like cookies.set()), document them on the same page. If two APIs are independent, they get separate pages.

Structure

Identify which category the API belongs to, then follow the corresponding template.

Categories

1. Function (cookies, fetch, generateStaticParams): signature, params/returns, methods table, examples
2. Component (Link, Image, Script): props summary table, individual prop docs, examples
3. File convention (page, layout, route): definition, code showing the convention, props, behavior, examples
4. Directive (use client, use cache): definition, usage, serialization/boundary rules, reference
5. Config option (basePath, images, etc.): definition, config code, behavioral sections

Template

---
title: {API name}
description: {API Reference for the {API name} {function|component|file convention|directive|config option}.}
---

{One sentence defining what it does and where it's used.}

```tsx filename="path/to/file.tsx" switcher
// Minimal working usage
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Reference

{For functions: methods/params table, return type.}
{For components: props summary table, then `#### propName` subsections.}
{For file conventions: `### Props` with `#### propName` subsections.}
{For directives: usage rules and serialization constraints.}
{For config: options table or individual option docs.}

### {Subsection name}

{Description + code example + table of values where applicable.}

## Good to know

- {Default behavior or implicit effects.}
- {Caveats, limitations, or version-specific notes.}
- {Edge cases the developer should be aware of.}

## Examples

### {Example name}

{Brief context, 1-2 sentences.}

```tsx filename="path/to/file.tsx" switcher
// Complete working example
```

```jsx filename="path/to/file.js" switcher
// Same example in JS
```

## Version History

| Version  | Changes         |
| -------- | --------------- |
| `vX.Y.Z` | {What changed.} |