Skip rendering work for off-screen OpenAPI blocks

[nolannbiron]

A customer page with 95 OpenAPI blocks — oeconnection.gitbook.io/partstech-partner-api/api-reference/v3 — is effectively unscrollable. Measured from its shipped HTML: 95 operation blocks, ~45,700 DOM elements, 6.4 MB of markup (8.2 MB with the RSC payload), and 95 position: sticky preview panes. Every operation is styled, laid out and painted on every frame, whether or not it is anywhere near the viewport. This is not specific to computed pages — it happens on any hand-authored page that drops many openapi-* blocks into a document, which is what this customer did.

content-visibility: auto on .openapi-block lets the browser skip that work for blocks that are off screen. The DOM is untouched, so the server HTML, find-in-page, #anchors and the outline all keep working — which is why this is CSS rather than unmounting nodes: SEO is the whole point of these pages.

contain-intrinsic-height: auto 1200px gives a skipped block its placeholder height. The auto keyword makes the browser remember each block's real height once rendered, so the estimate only ever applies to blocks never scrolled to; the plain-length declaration before it is a fallback for engines without auto sizing, where a skipped block would collapse to 0. 1200px is a reasoned guess, not a measurement — worth tuning on the preview with:

const h = [...document.querySelectorAll('.openapi-block')]
    .map((e) => e.getBoundingClientRect().height).sort((a, b) => a - b);
h[Math.floor(h.length / 2)];

PDF export lays the whole space out off screen, so body:has(.print-mode) and @media print opt out.

Not covered by this PR: hydration cost is unchanged — every block is a client component rendered with next/dynamic({ ssr: true }), so React still builds ~45k fibers on load. If scrolling is still rough on the preview, deferring hydration of off-screen blocks is the next lever. Payload size is also unchanged.

[changeset-bot]

🦋 Changeset detected

Latest commit: dea0146

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-82nqd4pmz-gitbook.vercel.app	✅
Cloudflare	https://c5461bd9-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-82nqd4pmz-gitbook.vercel.app/url/gitbook.com/docs	https://c5461bd9-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-82nqd4pmz-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://c5461bd9-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	21 changed, 2 ignored	Aug 14, 2026, 3:59 PM
customers-v2-vercel (Inspect)	⚠️ Changes detected (Review)	21 changed, 2 ignored	Aug 14, 2026, 4:10 PM
v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	4 changed	Aug 14, 2026, 3:59 PM
v2-vercel (Inspect)	⚠️ Changes detected (Review)	8 changed, 8 removed, 2 failures, 2 ignored	Aug 14, 2026, 4:12 PM

[github-actions]

Style invalidation on a large API reference

Elements restyled by opening one popup on the Snyk API reference. A share near or above 100% means the insertion restyles the whole document.

interaction	restyled	page	share	budget
openapi-select	6	10,856	0.1%	25%	✅
search	11,493	10,856	105.9%	125%	✅