[MohamedH1998]

Summary

Moves the API site's operation pages, Markdown twins and llms.txt from the site's own routing and page components to Nimbus. astro-fern still decides products, resources and URLs. A small adapter, prepareForgeApi, turns its output into the spec Nimbus renders.

Pages are 2–8× lighter and served 3–5× faster. In exchange, builds take longer: a cached rebuild takes about twice as long as main's, and preview starts in 13 s against 5 s.

This PR carries the Nimbus 0.19 upgrade from #68. main is merged in, and the sample picker keeps main's cf CLI, curl and Terraform, with cf CLI first.

Changes

Rendering

• Adapter (src/forge-api.ts). Adds Cloudflare titles, lifecycle order, request samples, response examples and Terraform data to the spec. Terraform is one sample joining every declaration example, as on main.
• Build. astro.config.mjs runs the adapter when the config loads and writes the spec, products and redirects to the git-ignored .forge/. The astroFern integration is removed.
• Routes. One Nimbus catch-all serves every API page. Nimbus serves llms.txt, per-section llms.txt, llms-full.txt and /<page>/index.md. The docs and live collections become Nimbus's api and apiPages.
• Dependencies. @cloudflare/nimbus-docs 0.19.3, openapi-sampler and @scalar/openapi-parser added; @astrojs/prism removed. Nimbus 0.19.3 is exempt from the workspace's minimum release age.

Components

• The Nimbus starter's API layout, sidebar, field rows and code rail live in src/components/ui/, with the building blocks they use: collapsible, layer card, pagination, popover, sidebar and version switcher. The site owns these files and edits them for Cloudflare: availability notices, Terraform, library cards on the home page, and the tooling sidebar.
• src/components/ui/** and src/lib/** are excluded from oxlint and oxfmt, so starter updates apply cleanly.
• Command pages move onto their own sidebar.

What looks different from main

• Header. The version picker is Nimbus's version switcher. It's no longer repeated in the mobile drawer, and a banner flags a deprecated version. The brand lines up with the sidebar column.
• Sidebar. Operations show method chips, and the filter reads "Filter sidebar".
• Page header. Title, then the endpoint box, then page actions. The box shows only the path after the server URL, as production does, and its button copies the full URL. A very long path is cut off rather than wrapped.
• Description. It opens the body above Authorization, so long descriptions no longer push the endpoint down. It is styled as prose: spaced headings, paragraphs and lists, and inline code as chips.
• Code rail. 30rem wide, down from 34rem. On wide screens it sits beside the reference, capped to the viewport. Its header stays put while the sample scrolls inside it in both directions; the response example has its own scroll box. Targets without a sample show a one-line placeholder.
• Keyboard. Tab moves picker → copy → sample → status tabs → response, each with a visible focus ring.
• Parameter links. A link to a field opens its collapsed parents and scrolls there once.
• Terraform. Declarations appear below the reference while the Terraform sample is selected, instead of replacing it. Their headings drop a level, and the "not implemented in Terraform" notice is gone.
• Home page. Lists every endpoint with a filter, loading 150 at a time as you scroll. Each later batch is also its own noindexed page, so readers without script can reach it. No last-updated date.
• Prev/next links at the end of every API page, so a reader at the bottom always has a next step.
• Details. Thin, tinted scrollbars, a new text selection colour, and the header height as a token.

URLs and agent files

• Alias operations, which main drops, redirect to their primary page with a 302, as do old section and moved-product URLs. A build fails if an alias has no primary page.
• /<page>.md 301s to /<page>/index.md.
• Markdown twins start with frontmatter, as developers.cloudflare.com's do: title and version. The description isn't repeated there, since the body has it. main's twins have none.
• llms.txt is now text/plain, not text/markdown.
• ?lang= only picks the sample shown first, and unknown values no longer 404. Per-language Markdown and llms.txt are gone. The Terraform sample's id is now hcl.
• /api/index.mdx is gone, because the home page moved into the API layout.
• The home page has no meta description. Section pages without a description get "
  API resources and endpoints.", and the 160-character cut is gone.

Other

• Icons. Only the icons the site uses are inlined. The Worker drops from 3.5 MB to 0.7 MB compressed.
• Off for now. Nimbus schema pages, and the spec download: Nimbus pretty-prints the spec to 36 MB, over the Workers asset limit. MDX validation is off because the site has no MDX pages.
• Tests. Playwright previews with --ignore-lock, and there's a new operation-terraform visual shot.
• README rewritten, including the Terraform removal checklist.

Validation

• Root pnpm check, pnpm typecheck and pnpm -r run test (459 passed).
• Site astro check (0 errors), build and test:e2e (38 passed). The end-to-end tests cover the sample picker, the redirects, the Markdown and llms.txt routes and the Terraform section.
• Checked in Chromium against main at 1440 px: endpoint box, code rail scrolling, tab order and focus rings, parameter links, and long descriptions in light and dark mode.

Performance against main. Both built locally from spec release openapi@bdea3bc5. Server times are medians of 15 requests; browser figures are medians of 3 loads.

	main	This PR
Operation page HTML	496 KB	124 KB
Product page HTML	473 KB	58 KB
Warm response, operation page	20 ms	5 ms
DOM elements, operation page	13,800	2,400
Largest contentful paint	108 ms	76 ms
JavaScript per page	12 KB	36 KB
Requests per page	14	24
Worker, compressed	4.1 MB	0.7 MB
Static assets	55 MB, 3,066 files	210 MB, 6,692 files
Cold build	30 s	58–71 s
Rebuild, cache warm	26 s	47 s
Peak build memory	2.4 GB	3.1–4.0 GB
Preview ready	5 s	13 s

Nimbus prepares data for every page at build time, which is what makes pages faster, and caches that work between builds. The remaining rebuild gap is mostly Astro's server build, about 40 s against 20 s on main.

[pkg-pr-new]

npm i https://pkg.pr.new/cloudflare/forge/@cloudflare/forge@91

commit: 5f62134