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: 3e31638

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-hxa0n9y0h-gitbook.vercel.app	✅
Cloudflare	https://607708f7-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-hxa0n9y0h-gitbook.vercel.app/url/gitbook.com/docs	https://607708f7-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-hxa0n9y0h-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://607708f7-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)	👍 Changes approved	1 changed, 4 added	Nov 5, 2025, 1:09 PM
v2-cloudflare (Inspect)	👍 Changes approved	1 changed	Nov 5, 2025, 1:12 PM
v2-vercel (Inspect)	👍 Changes approved	2 changed	Nov 5, 2025, 1:12 PM

[conico974]

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

[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.