Introduce an "area" concept, so we aren't locked into a single layout under the "API" section of the docs site.

[borland]

Background

The docs site now has two distict sections; the main docs, and the api docs.

API docs have a different layout with different column sizing, and they also have their own specific navigation tree, which is tailored to the API, and does things like rendering icons next to GET/POST/PUT requests.

Previously, the layout dictated which area/navigation tree a page was put in. If a page wanted to be in the API tree, then it was forced to use the API's column structure. We want to mix in user-written pages along with the auto-generated ones, and forcing user-written pages to use the API column structure just looks bad.

Also, in future, we intend to have areas for "Learn" and "CLI", which would have their own nav trees

Results

This PR adds the formal concept of an area. The area is now what dictates which navigation tree a page appears in, and we can use different layouts within any given area.

• Pages can now specify an area explicitly via their yaml frontmatter.
• If they don't, an area will in inferred from the path. Things in the docs/api folder get the API area, everything else gets the Docs area.
• We can extend this to make areas for CLI/Learn later

Note: The TopNav hasn't been touched. We should update it so when you click "API" it takes you to the API area's landing page, but that will come later

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3398.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[enf0rc3]

Drive-by review: I pointed Claude Code at this PR, so the findings below are an AI's rather than mine. I checked the line references and grepped the counts it cites, and left the rest unverified. Ignore whatever is wrong or not worth the effort.

The design reads well. Things it checked that could have broken quietly and didn't: all 106 pages under src/pages/docs/api use Api.astro and no Api.astro page lives outside that path, so the layout→path switch moves no page today; areas.ts has no top-level posts.all(), so it doesn't reopen the import-cycle trap that urlsByFile() documents; ApiNavigation tolerates absent headings, so Default.astro rendering it is safe.

One caveat on all of it: nothing on the branch declares area: yet (0 pages, and 0 paged: pages), so the three correctness items are latent. They land on whichever page uses the escape hatch first.

EDIT: Ignore the Claude review, time for a human review, (i removed the comments)

[enf0rc3]

Looks good, i see the benefits of this for nav, really cleans it up