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()

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.} |

Category-specific notes:

• Functions: Lead with the function signature and

  await

  if async. Document methods in a table if the return value has methods (like

  cookies

  ). Document options in a separate table if applicable.
• Components: Start with a props summary table (

  | Prop | Example | Type | Required |

  ). Then document each prop under

  #### propName

  with description, code example, and value table where useful.
• File conventions: Show the default export signature with TypeScript types. Document each prop (

  params

  ,

  searchParams

  , etc.) under

  #### propName

  with a route/URL/value example table.
• Directives: No

  ## Reference

  section. Use

  ## Usage

  instead, showing correct placement. Document serialization constraints and boundary rules.
• Config options: Show the

  next.config.ts

  snippet. Use subsections for each behavioral aspect.

Rules

1. Lead with what it does. First sentence defines the API. No preamble.
2. Show working code immediately. A minimal usage example appears right after the opening sentence, before

   ## Reference

   .
3. Use

   switcher

   for tsx/jsx pairs. Always include both. Always include

   filename="path/to/file.ext"

   .
4. Use

   highlight={n}

   for key lines. Highlight the line that demonstrates the API being documented.
5. Tables for simple APIs, subsections for complex ones. If a prop/param needs only a type and one-line description, use a table row. If it needs a code example or multiple values, use a

   ####

   subsection.
6. Behavior section uses

   > **Good to know**:

   or

   ## Good to know

   . Use the blockquote format for brief notes (1-3 bullets). Use the heading format for longer sections. Not "Note:" or "Warning:".
7. Examples section uses

   ### Example Name

   subsections. Each example solves one specific use case.
8. Version History table at the end. Include when the API has changed across versions. Omit for new APIs.
9. No em dashes. Use periods, commas, or parentheses instead.
10. Mechanical, observable language. Describe what happens, not how it feels. "Returns an object" not "gives you an object".
11. Link to related docs with relative paths. Use

    /docs/app/...

    format.
12. No selling or justifying. No "powerful", "easily", "simply". State what the API does.

cookies

<Link>

<a>

Workflow

1. Ask for reference material. Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
2. Identify the API category (function, component, file convention, directive, config).
3. Research the implementation. Read the source code to understand params, return types, edge cases, and defaults.
4. Check e2e tests. Search

   test/

   for tests exercising the API to find real usage patterns, edge cases, and expected behavior.
5. Check existing related docs for linking opportunities and to avoid duplication.
6. Write using the appropriate category template. Follow the rules above.
7. Review against the rules. Verify: one sentence opener, immediate code example, correct

   switcher

   /

   filename

   usage, tables vs subsections, "Good to know" format, no em dashes, mechanical language.

References

Read these pages in

docs/01-app/03-api-reference/

• 04-functions/cookies.mdx

  - Function with methods table, options table, and behavior notes

• 03-file-conventions/page.mdx

  - File convention with props subsections and route/URL/value tables

• 02-components/link.mdx

  - Component with props summary table and detailed per-prop docs

• 01-directives/use-client.mdx

  - Directive with usage section and serialization rules

• 04-functions/fetch.mdx

  - Function with troubleshooting section and version history