Add contextual help explaining what a "Featured image" is

[simison]

What problem does this address?

At page/post settings, there's featured image section:

We don't explain what this does, or why is it important.

What is your proposed solution?

Add some explanation and link to the documentation.

AMP plugin actually does add a small explanation, but we could do this directly in Gutenberg. (cc @westonruter).

Here's screenshot with AMP plugin enabled:

Similar to #30872

[karmatosed]

@simison could you put the messaaging 'in' the block itself that says 'set featured image'? I wonder if there's an option here to combine both together over have 2 areas of text?

[mtias]

That text doesn't seem to add anything regarding why it's recommended?

[simison]

@mtias I agree, text needs to be something better and/or link to more in-depth docs. That was just an example of AMP plugin adding that exact text currently.

[westonruter]

Yes, the text should be better. It is too vague. In the AMP plugin context, the featured image is used in the Schema.org metadata that it adds to the page. So this will ensure that the post will have the expected image when it shows up in Search or when shared on social media. Jetpack and Yoast similarly use the featured image to determine what is included in the metadata for search/social.

However, since WordPress core doesn't currently include Schema.org metadata generation, I'm not sure that such a notice would be worthwhile at the moment.

cc @adamsilverstein who has been thinking about Schema.org in core.

[joedolson]

At the moment, I'm not sure what core can say about what benefits you can get from setting the featured image - does core, practically speaking, have a way of knowing how the featured image might be used?

[westonruter]

No. Not without rendering the theme's singular template for the given post and checking whether the post_thumbnail_html filter applies, for example. But even that wouldn't catch cases where the theme grabs the image via get_post_thumbnail_id() and renders it using wp_get_attachment_image().

In practice, though, all themes will display the featured image prominently at the top of the post. So if a user attempts to add an image block as the first block in the content, this seems like an opportunity where the featured image could be mentioned somehow. Like, if a user adds a content-initial image it could ask if they want to use it as a featured image instead, and then explain what the difference is. Maybe it could even be transformed from a block into a featured image at that point. For non-FSE themes, the UI for setting the featured image would seem better under the title as a Post Featured Image block.

[carolinan]

The current featured image block behavior is strange, because you can add a featured image block even without the theme_support. It is the theme_support that adds the featured image section to the post setting sidebar.

This section is (only) useful when you want a featured image in for example a query/loop but not the post content.
If you only want the featured image in the content, then you don't need to use this setting, you just upload an image when you place the block.
So perhaps the text should include that information.
"Set a featured image if you want to display the image outside the content"

[skorasaurus]

ref #27617

[altivero]

How about:
"This image represents this post or page usually in thumbnail form in a list of posts or pages"
This would cover the most used case and give new users a good example to visualize.

[bph]

I would add "The Featured image is also used when your post is shared on social media, i.e. Twitter, Facebook or LinkedIn".

[ianstewart]

Is there a great WordPress.org page that explains featured images and why one would want to use them from a writing/publishing perspective?

There's a start of an explanation in the themer/dev-oriented theme handbook.

https://developer.wordpress.org/themes/functionality/featured-images-post-thumbnails/

I don't think that page is the best to link to from the editor but if we take the intro paragraph …

Featured images (also sometimes called Post Thumbnails) are images that represent an individual Post, Page, or Custom Post Type. When you create your Theme, you can output the featured image in a number of different ways, on your archive page, in your header, or above a post, for example.

That has a good start.

Featured images are images that represent an individual Post, Page, or Custom Post Type. Themes can output the featured image in a number of different ways, on your Blog page, in your header, or above a post, and when your post is shared on social media, like Twitter, Facebook or LinkedIn. Read more about Featured Images.

[bph]

That's a good point @ianstewart I don't think there is a page for content creators that explains Featured Images in more detail... I only found one reference and that pretty much in the same context, also not explanation why it's important. All other references were in context of individual themes.
WordPress.com documentation does this better

[noisysocks]

The popover that #42352 introduces gives us a natural place to place help text like this cc. @javierarce.

[joyously]

This issue is supposed to handle 12742, which is about the existing PHP filter for this that doesn't work in the block editor.