Update image documentation to have more details for picture and srcset_image tags (#11167)

docs/extending/rich_text_internals.md

@@ -42,7 +42,7 @@ which is converted into an `img` element when rendered:
     alt="A pied wagtail"
     class="richtext-image left"
     height="294"
-    src="/media/images/pied-wagtail.width-500_ENyKffb.jpg"
+    src="/media/images/pied-wagtail.width-500.jpg"
     width="500"
 />
 ```

docs/reference/jinja2.md

@@ -92,7 +92,13 @@ Browsers will select the most appropriate image to load based on [responsive ima
 The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential unless you store the output of `srcset_image` for later use.
 
 ```html+jinja
-{{ srcset_image(page.header_image, "fill-{512x100,1024x200}", sizes="100vw", class="header-image") }}
+{{ srcset_image(page.photo, "width-{400,800}", sizes="(max-width: 600px) 400px, 80vw") }}
+```
+
+This outputs:
+
+```html
+<img srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" sizes="(max-width: 600px) 400px, 80vw" width="400" height="300">
 ```
 
 Or resize an image and retrieve the renditions for more bespoke use:
@@ -104,19 +110,39 @@ Or resize an image and retrieve the renditions for more bespoke use:
 
 ### `picture()`
 
-Resize or convert an image, rendering a `<picture>` tag including multiple `source` formats with `srcset` for multiple sizes.
+Resize or convert an image, rendering a `<picture>` tag including multiple `source` formats with `srcset` for multiple sizes, and a fallback `<img>` tag.
 Browsers will select the [first supported image format](https://web.dev/learn/design/picture-element/#image-formats), and pick a size based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
 
 `picture` can render an image in multiple formats:
 
 ```html+jinja
-{{ picture(page.header_image, "format-{avif,jpeg}") }}
+{{ picture(page.photo, "format-{avif,webp,jpeg}|width-400") }}
+```
+
+This outputs:
+
+```html
+<picture>
+    <source srcset="/media/images/pied-wagtail.width-400.avif" type="image/avif">
+    <source srcset="/media/images/pied-wagtail.width-400.webp" type="image/webp">
+    <img src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
+</picture>
 ```
 
 Or render multiple formats and multiple sizes like `srcset_image` does. The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential when the picture tag renders images in multiple sizes:
 
 ```html+jinja
-{{ picture(page.header_image, "format-{avif,jpeg}|fill-{512x100,1024x200}", sizes="100vw") }}
+{{ picture(page.header_image, "format-{avif,webp,jpeg}|width-{400,800}", sizes="80vw") }}
+```
+
+This outputs:
+
+```html
+<picture>
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w" type="image/avif">
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w" type="image/webp">
+    <img sizes="80vw" srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
+</picture>
 ```
 
 Or resize an image and retrieve the renditions for more bespoke use:

docs/releases/5.2.md

@@ -25,11 +25,27 @@ The page explorer listing view has been redesigned to allow improved navigation
 
 ### Responsive & multi-format images with the picture tag
 
-Wagtail has new template tags to reduce the performance and environmental footprint of images:
+Wagtail has new template tags to reduce the loading time and environmental footprint of images:
 
  * The `picture` tag generates images in multiple formats and-or sizes in one batch, creating an HTML `<picture>` tag.
  * The `srcset_image` tag generates images in multiple sizes, creating an `<img>` tag with a `srcset` attribute.
 
+As an example, the `picture` tag allows generating six variants of an image in one go:
+
+```html+django
+{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %}
+```
+
+This outputs:
+
+```html
+<picture>
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w" type="image/avif">
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w" type="image/webp">
+    <img sizes="80vw" srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
+</picture>
+```
+
 We expect those changes to greatly reduce the weight of images for all Wagtail sites. We encourage all site implementers to consider using them to improve the performance of the sites and reduce their carbon footprint. For further details, For more details, see [](multiple_formats) and [](responsive_images). Those new template tags are also supported in Jinja templates, see [](jinja2) for the Jinja API.
 
 This feature was developed by Paarth Agarwal and Thibaud Colas as part of the Google Summer of Code program and a [partnership with the Green Web Foundation](https://www.thegreenwebfoundation.org/news/working-with-the-wagtail-community-on-the-summer-of-code/) and Green Coding Berlin, with support from Dan Braghiș, Thibaud Colas, Sage Abdullah, Arne Tarara (Green Coding Berlin), and Chris Adams (Green Web Foundation). We also thank Aman Pandey for introducing [AVIF support](image_file_formats) in Wagtail 5.1, Andy Babic for creating [`AbstractImage.get_renditions()`](image_renditions_multiple) in the same release; and Storm Heg, Mitchel Cabuloy, Coen van der Kamp, Tom Dyson, and Chris Lawton for their feedback on [RFC 71](https://github.com/wagtail/rfcs/pull/71).

docs/topics/images.md

@@ -36,35 +36,65 @@ Note that a space separates `[image]` and `[resize-rule]`, but the resize rule m
 To render an image in multiple formats, you can use the `picture` tag:
 
 ```html+django
-{% picture page.photo width-400 format-{avif,jpeg} %}
+{% picture page.photo format-{avif,webp,jpeg} width-400 %}
 ```
 
-Compared to `image`, this will render a `<picture>` element with one `<source>` element per format. The browser [picks the first format it supports](https://web.dev/learn/design/picture-element/#source), or defaults to a fallback `<img>` element.
+Compared to `image`, this will render a `<picture>` element with a fallback `<img>` within and one `<source>` element per extra format. The browser [picks the first format it supports](https://web.dev/learn/design/picture-element/#source), or defaults to the fallback `<img>` element. For example, the above will render HTML similar to:
 
-`picture` can also be used with responsive image resize rules.
+```html
+<picture>
+    <source srcset="/media/images/pied-wagtail.width-400.avif" type="image/avif">
+    <source srcset="/media/images/pied-wagtail.width-400.webp" type="image/webp">
+    <img src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
+</picture>
+```
+
+In this case, if the browser supports the [AVIF](https://en.wikipedia.org/wiki/AVIF) format it will load the AVIF file. Otherwise, if the browser supports the [WebP](https://en.wikipedia.org/wiki/WebP) format, it will try to load the WebP file. If none of those formats are supported, the browser will load the JPEG image. The order of the provided formats isn’t configurable – Wagtail will always output source elements in the following order: AVIF, WebP, JPEG, PNG, GIF. This ensures the most optimized format is provided whenever possible.
+
+The `picture` tag can also be used with multiple image resize rules to generate responsive images.
 
 (responsive_images)=
 
 ## Responsive images
 
-Wagtail provides `picture` and `srcset_image` template tags which can generate an `<img>` tag with a `srcset` attribute. This allows browsers to select the most appropriate image file to load based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+Wagtail provides `picture` and `srcset_image` template tags which can generate image elements with `srcset` attributes. This allows browsers to select the most appropriate image file to load based on [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
 
-The syntax for `srcset_image` is the same as `image, with two exceptions:
+The syntax for `srcset_image` is the same as `image`, with two exceptions:
 
 ```html+django
-{% srcset_image [image] [resize-rule-with-brace-expansion] sizes="100vw" %}
+{% srcset_image [image] [resize-rule-with-brace-expansion] sizes="[my source sizes]" %}
 ```
 
-- The resize rule should be provided with multiple sizes in a brace-expansion pattern, like `width-{200,400}`. This will generate the `srcset` attribute, with as many URLs as there are sizes defined in the resize rule.
+- The resize rule should be provided with multiple sizes in a brace-expansion pattern, like `width-{200,400}`. This will generate the `srcset` attribute, with as many URLs as there are sizes defined in the resize rule, and one width descriptor per URL. The first provided size will always be used as the `src` attribute, and define the image’s width and height attributes, as a fallback.
 - The [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes) attribute is essential. This tells the browser how large the image will be displayed on the page, so that it can select the most appropriate image to load.
 
-Here is an example with the `picture` tag:
+Here is an example of `srcset_image` in action, generating an `srcset` attribute:
+
+```html+django
+{% srcset_image page.photo width-{400,800} sizes="(max-width: 600px) 400px, 80vw" %}
+```
+
+This outputs:
+
+```html
+<img srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" sizes="(max-width: 600px) 400px, 80vw" width="400" height="300">
+```
+
+And here is an example with the `picture` tag:
 
 ```html+django
-{% picture page.photo fill-{512x100,1024x200} format-{avif,jpeg} sizes="100vw" %}
+{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %}
 ```
 
-This will generate a `<picture>` element with one `<source>` for AVIF and one fallback `<img>` with JPEG. Both the source and fallback image will have the `sizes` attribute, and a `srcset` with two URLs each.
+This outputs:
+
+```html
+<picture>
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w" type="image/avif">
+    <source sizes="80vw" srcset="/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w" type="image/webp">
+    <img sizes="80vw" srcset="/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w" src="/media/images/pied-wagtail.width-400.jpg" alt="A pied Wagtail" width="400" height="300">
+</picture>
+```
 
 (available_resizing_methods)=
 

docs/topics/writing_templates.md

@@ -98,6 +98,42 @@ For example:
 
 See [](image_tag) for full documentation.
 
+### Images in multiple formats
+
+The `picture` tag works like `image`, but allows specifying multiple formats to generate a `<picture>` element with `<source>` elements and a fallback `<img>`.
+
+For example:
+
+```html+django
+{% load wagtailimages_tags %}
+...
+
+{% picture page.photo format-{avif,webp,jpeg} width-400 %}
+```
+
+See [](multiple_formats) for full documentation.
+
+### Images in multiple sizes
+
+The `srcset_image` tag works like `image`, but allows specifying multiple sizes to generate a `srcset` attribute and leverage  [responsive image rules](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+
+For example:
+
+```html+django
+{% load wagtailimages_tags %}
+...
+
+{% srcset_image page.photo width-{400,800} sizes="(max-width: 600px) 400px, 80vw" %}
+```
+
+This can also be done with `picture`, to generate multiple formats and sizes at once:
+
+```html+django
+{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes="80vw" %}
+```
+
+See [](responsive_images) for full documentation.
+
 (rich_text_filter)=
 
 ## Rich text (filter)