Repository navigation
docs: explain how open-graph image-width and image-height apply - #2282
Merged
Merged
Conversation
The image rows of both social metadata tables said a declared image-width/image-height improves "your Twitter Card". Twitter Card metadata never reads a declared size; only Open Graph does. With site-url set, Quarto measures PNG images and uses that size over a declared one. From Quarto 1.11 (quarto-dev/quarto-cli#15040), a declared size is kept for images Quarto can't measure (JPEG, SVG, ...), and a page that brings its own image no longer inherits the size declared for the site image. Explain both in the Open Graph table, and point the Twitter Card row there instead.
Contributor
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-2282.quarto.org 🔄 Modified Documents |
The image row described only PNG measurement and suggested JPEG as a case for declared sizes. Since quarto-dev/quarto-cli#15050, Quarto also measures JPEG, so declared sizes only matter for remote images and formats like WebP or GIF. quarto-dev/quarto-cli#15040 also stops a page image from inheriting the sizes declared in website: open-graph. The check is whether the page supplies an image, not whether it differs from the site image, and only the page's open-graph block is read, not top-level image-width/height. Sites without site-url that used the site sizes as defaults lose those tags, so document the migration through page or _metadata.yml open-graph metadata, and note that directory sizes also apply to the site image on pages without their own image. All statements checked by rendering test sites with a 1.11 dev build and with 1.10.19.
Contributor
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-2282.quarto.org 🔄 Modified Documents |
2 of 5 tasks
cderv
added a commit
to quarto-dev/quarto-cli
that referenced
this pull request
Oct 15, 2026
Remove the top-level `image-width` and `image-height` options, which nothing read. Open Graph sizes come from `open-graph` or from measuring the image. Because the schema typed them as strings, a numeric value such as `image-width: 1200` failed the render, for an option that did nothing. Wiring them up was rejected: the same names already size the about-page image, so a top-level meaning would be ambiguous. - Remove both keys from the website document schema. Front matter accepts undeclared keys, so numeric and string values now render and are ignored. - Point the `image` option description at `open-graph` for declaring the preview image size. See #15040 and quarto-dev/quarto-web#2282 for the sizing rules and the existing "aren't used" note. Related to #12016
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to quarto-dev/quarto-cli#15040, which fixes quarto-dev/quarto-cli#12016 for Quarto 1.11, and quarto-dev/quarto-cli#15050, which adds JPEG measurement.
The
imagerows of both social metadata tables said thatimage-widthandimage-heightimprove "your Twitter Card". Twitter Card metadata never uses a declared size, only Open Graph does. The Twitter Card row now points to the Open Graph section.A new "Image Size" section under Open Graph explains how a declared size applies. With
site-urlset, Quarto measures local PNG and JPEG images and uses that size over a declared one, so declared sizes matter for remote images and formats Quarto can't measure, such as WebP or GIF. Sizes inwebsite: open-graphdescribe the site image: a page that supplies its own image gets only the sizes in its ownopen-graphmetadata, even when it repeats the site image.That last part changes behavior for sites without
site-url, where page images used to inherit the site sizes. The section shows how to restore them through page or_metadata.ymlopen-graphmetadata.This targets
prereleasedirectly, as the behavior is new in 1.11.