Endpoint pages and the sidebar

What every endpoint page includes

Each operation gets a page with its method and path, parameters, request body, and response schemas — with the first response status open on load so the schema tree is immediately visible — plus an interactive playground: readers fill parameters, send real requests (proxied to avoid CORS friction), and see live responses. The server URL is shown and editable. Deep links work down to individual response schemas.

Hand-written pages in an API section

An API reference section is still a content folder — MDX placed in it renders in the same sidebar as the generated endpoints:

content/docs/payments/api-reference/
├── meta.json
├── index.mdx            ← overview, listed above the endpoints
└── authentication.mdx

With no meta.json, your pages simply list above the endpoint categories. With one, you control the story the sidebar tells:

{ "pages": ["...", "---Getting Started---", "authentication"] }

Attaching endpoint categories to your sections

The ---Label--- separators in meta.json do double duty: your pages go under them, and generated categories can too, via the per-spec section and sectionByTag options:

{
  "spec": "payments.json",
  "useFirstTagOnly": true,
  "sectionByTag": { "banking": "Banking API", "energy": "Energy API" }
}

{ "pages": ["index", "---Core Resources---", "linking-accounts", "---Banking API---", "---Energy API---"] }

Result: operations tagged banking render under the "Banking API" heading, energy under "Energy API", and the tag names themselves stop appearing as categories. A labeled section with no pages of its own is valid — it exists to receive categories. Section labels match case-insensitively.

This is how you make one sidebar read as a single designed document — overview, hand-written concept pages, then generated resources, each under intentional headings. The live demo on this site uses exactly this mechanism.

Where specs come into it

Category formation (tags, ordering, merging) is configured per spec — see Specs. Everything on this page composes with versions and groups: each version or group applies its own spec options and can carry its own MDX pages.