The image is rather big, and takes up a large amount of space in the preview disproportionate (IMO) relative to its value for readers.

IIRC this is the standard/recommended size, but otherwise I agree that it could be smaller.

Of the options listed, I prefer Python Docs

+1

but I imagine the PSF trademarks committee might need to review it if its something other than one of the official logotypes.@malemburg ?

We have already checked with them while working on the Devguide PR and mentioned that we are planning to do the same on related repos, so everything should be already ok on this front.

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

https://developers.facebook.com/docs/sharing/webmasters/images says:

Requirements

• The minimum allowed image dimension is 200 x 200 pixels.
• The size of the image file must not exceed 8 MB.
• Use images that are at least 1200 x 630 pixels for the best display on high resolution devices. At the minimum, you should use images that are 600 x 315 pixels to display link page posts with larger images.
• If your image is smaller than 600 x 315 px, it will still display in the link page post, but the size will be much smaller.
• We've also re-designed link page posts so that the aspect ratio for images is the same across desktop and mobile Feed. Try to keep your images as close to 1.91:1 aspect ratio as possible to display the full image in Feed without any cropping.

As a quick test, autocropping to 1022 x 330:

https://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html

Gives:

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fhugovk-cpython.readthedocs.io%2Fen%2Fadd-og-metadata2%2Fwhatsnew%2F3.12.html

• We should backport it to at least the primary/default version site for this to have proper effect, but can we add the extension in a way that will gracefully fallback if the plugin is not installed (e.g. on downstream redistributors, who are unlikely to need, want or have it)?

@AA-Turner Do you know if this is possible with Sphinx?

"Python Docs", single line or multiline?

(Font sizes 160, 210, 230)

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

Okay; could you try to output it at 482 x 200 and see if it displays smaller? Or at the recommended minimum size?

@AA-Turner Do you know if this is possible with Sphinx?

conf.py is just a Python script; couldn't you do

try:importsphinxext.opengraphexceptImportError:passelse:extensions.append("sphinxext.opengraph")

"Python Docs", single line or multiline?

I guess multiline, if its a mixed aspect ratio. If we must use the space, may as well get as much out of it as we can...

I addedskip-issue since the issue is on another repo, but left outskip-news since we might want to write a news entry if we're adding a new docs dependency, if an optional one.

Yes, the required minimum is 200 x 200 and recommended minimum is 1200 x 630, with 1.91:1 aspect ratio.

Okay; could you try to output it at 482 x 200 and see if it displays smaller?

Here's how 482 x 200 looks:

(Note to self: python og_image.py --text "Python Docs" --logo tests/python-logo.png --font ../pythondotorg/static/fonts/FluxRegular.ttf --text "Python Docs" --size 100 -W 482 -H 200 -lw 15 -lh 15)

This is smaller because Facebook says:

If your image is smaller than 600 x 315 px, it will still display in the link page post, but the size will be much smaller.

Or at the recommended minimum size?

Therecommended minimum 1200 x 630 that we started with. The "absolute" minimum is 200 x 200, it's just the icon and looks like:

(python og_image.py --text "Python Docs" --logo tests/python-logo.png --font ../pythondotorg/static/fonts/FluxRegular.ttf --text "Python Docs" --size 100 -W 200 -H 200 -lw 0 -lh 0)

conf.py is just a Python script; couldn't you do

try:importsphinxext.opengraphexceptImportError:passelse:extensions.append("sphinxext.opengraph")

Ah yes, thanks :)

I guess multiline, if its a mixed aspect ratio. If we must use the space, may as well get as much out of it as we can...

👍

but I imagine the PSF trademarks committee might need to review it if its something other than one of the official logotypes.@malemburg ?

We have already checked with them while working on the Devguide PR and mentioned that we are planning to do the same on related repos, so everything should be already ok on this front.

Please send in the final version for official approval. The versions I'm seeing on this ticket mostly appear fine. Just please make sure that the logo is not shown cut-off in parts. I know that this is difficult with social media links, but it would be good to at least have the complete logo shown in the previews.

The smaller version takes up a lot less unnecessary space, though it does omit the "Python Docs" nameplate/logotype. Naively to me, the former would seem worth it, but I don't have the same background in the uses of opengraph metadata, beyond anecdotal experience with the displayed previews a handful of common places. What do others think?

Here's a whole load of demos with various sizes:

• https://hugovk.neocities.org/og-test/200x200.html
• https://hugovk.neocities.org/og-test/315x315.html
• https://hugovk.neocities.org/og-test/400x400.html
• https://hugovk.neocities.org/og-test/450x450.html
• https://hugovk.neocities.org/og-test/482x200.html
• https://hugovk.neocities.org/og-test/500x500.html
• https://hugovk.neocities.org/og-test/599x599.html
• https://hugovk.neocities.org/og-test/600x600.html
• https://hugovk.neocities.org/og-test/1022x330.html
• https://hugovk.neocities.org/og-test/1200x630.html

I think the square logo version without the "Python Docs" text is quite good, we're not showing a big banner photo and it shows more of the relevant text too.

400x400 seems to be the upper bound to still show as a square logo:

Here's 200x200, looks about the same:

In Discord:

In Slack:

So I think 200x200 is a good one to use. I'll update this PR and add a bit of padding too so it's not too close to the border for Facebook.

Updated to 200x200 logo with 5px padding, demo athttps://hugovk-cpython.readthedocs.io/en/add-og-metadata2/whatsnew/3.12.html

One data point that might be relevant to the discussion is that (at least on Discord) clicking on the image just opens the image -- not the link.

This behavior is useful when sharing cat pics from your favorite social media website, since you mostly care about the pic itself (and you would generally be better off avoiding the comment section). However in our case we don't care about the image itself, and having such a big image will just increases the chances that the user will click that instead of the actual link.

IOW, the 200x200 logo might be a better fit for our use-case.

One data point that might be relevant to the discussion is that (at least on Discord) clicking on the image just opens the image -- not the link.

Hmm, interesting...I wasn't aware of this behavior, though this tends to imply that either it isn't widespread, or because I as a user have never actually tried to click the image.

Thanks@hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

GH-100115 is a backport of this pull request to the3.11 branch.

Backporting to 3.11, so we get it under the default/3/ as well.