The reference collection is where stable, lookup-friendly material belongs. Keep it factual, compact, and easy to scan so readers can move from concept pages in /docs to concrete details without changing mental models.

What belongs here

Use the reference section for information that readers are likely to revisit:

  • authentication rules
  • request and response shapes
  • error formats
  • field-level constraints

Narrative setup, onboarding advice, and editorial explanation usually fit better in /docs.

Authoring pattern

The reference pages use the same frontmatter contract as the docs pages:

---
title: Authentication
description: Explain how clients prove identity before making requests.
section: Core
order: 1
---

That keeps the shared sidebar, page metadata, and prev/next navigation automatic.

Suggested structure

Most teams benefit from a simple split:

  1. Keep /docs for onboarding and workflows.
  2. Keep /reference for stable definitions and lookup material.
  3. Link between the two whenever a guide depends on a concrete API shape.

Start with Authentication to see the pattern in practice.