Support custom cover heights

[viktorrenkema]

This PR handles the GBO-side of enabling cover height resizing. The basic idea is:

1. by default, we handle cover images the same as usual (aka there's a fixed aspect ratio as recommended in the docs that we adhere to, so this can lead to cover images of e.g. < 100px tall on smaller viewports)
2. if height exists on the page cover, it means the cover was resized. because we can't/shouldnt enforce an aspect ratio on a cover that has a dynamic height, different logic kicks in to determine the appropriate height depending on the dimensions so that the entire image is contained within the cover

The previous PR was reverted, as we didn't do step 1 above: we applied the 'new' sizing rules to existing page covers, which causes a lot of existing page covers to regress.

To help explain how a page cover has a fixed aspect ratio by default but how setting a height will impact that, we have tooltip UI in the editor + I have a CR ready to add more details in the support article.

CleanShot.2025-11-03.at.15.21.03.mp4

[changeset-bot]

⚠️ No Changeset found

Latest commit: cc4de25

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-481r8zt3c-gitbook.vercel.app	✅
Cloudflare	https://aedccb4e-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-481r8zt3c-gitbook.vercel.app/url/gitbook.com/docs	https://aedccb4e-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-481r8zt3c-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://aedccb4e-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 (Inspect)	✅ No changes detected	-	Nov 3, 2025, 2:15 PM
v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	1 changed	Nov 3, 2025, 2:18 PM
v2-vercel (Inspect)	👍 Changes approved	3 changed	Nov 3, 2025, 2:17 PM

[conico974]

Isn't it an issue that both light and dark image use the same sizes/aspect-ratio/position ?

[conico974]

I don't understand why we take the dark one here. Everywhere else it tries from light image first

[viktorrenkema]

I get what you mean, but it was intentional though. Its to account for if the dark img exists, it means it was intentionally uploaded as the light is the default and dark an explicit opt-in. So when we get into the situation where the img didnt ship with a size payload and we manually need to check the dimensions, we just first check if the dark one exists here to avoid always going for the light one directly and possibly not accounting for a dark mode with differign dimensions. We still fallback to light anyway if there is no dark one.

[viktorrenkema]

Isn't it an issue that both light and dark image use the same sizes/aspect-ratio/position ?

Yeah it is, I listed the same as a current limitation somewhere in another PR. I chatted about it with samy but while it'd be nice to support heights and object fit on both dark and light mode individually, its just not included yet in this feature release.