Mention using the `image_url` tag for increased performance on image URLs

CHANGELOG.txt

@@ -53,6 +53,7 @@ Changelog
  * Implement new "minimap" component for the page editor (Thibaud Colas)
  * The `image_url` template tag, when using the serve view to redirect rather than serve directly, will now use temporary redirects with a cache header instead of permanent redirects (Jake Howard)
  * Add new test assertions to `WagtailPageTestCase` - `assertPageIsRoutable`, `assertPageIsRenderable`, `assertPageIsEditable`, `assertPageIsPreviewable` (Andy Babic)
+ * Add documentation to the performance section about how to better create image URLs when not used directly on the page (Jake Howard)
  * Fix: Prevent `PageQuerySet.not_public` from returning all pages when no page restrictions exist (Mehrdad Moradizadeh)
  * Fix: Ensure that duplicate block ids are unique when duplicating stream blocks in the page editor (Joshua Munn)
  * Fix: Revise colour usage so that privacy & locked indicators can be seen in Windows High Contrast mode (LB (Ben Johnston))

docs/advanced_topics/images/image_serve_view.md

@@ -43,6 +43,8 @@ page of any image by clicking the "URL generator" button on the right hand side.
 
 This interface allows editors to generate URLs to cropped versions of the image.
 
+(dynamic_image_urls)=
+
 ### Generating dynamic image URLs in Python
 
 Dynamic image URLs can also be generated using Python code and served to a

docs/advanced_topics/performance.md

@@ -44,6 +44,20 @@ CACHES = {
 }
 ```
 
+### Image URLs
+
+If all you need is the URL to an image (such as for use in meta tags or other tag attributes), it is likely more efficient to use the [image serve view](using_images_outside_wagtail) and `{% image_url %}` tag:
+
+```html+django
+<meta property="og:image" content="{% image_url page.hero_image width-600 %}" />
+```
+
+Rather than finding or creating the rendition in the page request, the image serve view offloads this to a separate view, which only creates the rendition when the user requests the image (or returning an existing rendition if it already exists). This can drastically speed up page loads with many images. This may increase the number of requests handled by Wagtail if you're using an external storage backend (for example Amazon S3).
+
+Another side benefit is it prevents errors during conversation from causing page errors. If an image is too large for Willow to handle (the size of an image can be constrained with [`WAGTAILIMAGES_MAX_IMAGE_PIXELS`](wagtailimages_max_image_pixels)), Willow may crash. As the resize is done outside the page load, the image will be missing, but the rest of the page content will remain.
+
+The same can be achieved in Python using [`generate_image_url`](dynamic_image_urls).
+
 ### Search
 
 Wagtail has strong support for [Elasticsearch](https://www.elastic.co) - both in the editor interface and for users of your site - but can fall back to a database search if Elasticsearch isn't present. Elasticsearch is faster and more powerful than the Django ORM for text search, so we recommend installing it or using a hosted service like [Searchly](http://www.searchly.com/).

docs/reference/settings.md

@@ -302,6 +302,8 @@ WAGTAILIMAGES_MAX_UPLOAD_SIZE = 20 * 1024 * 1024  # 20MB
 
 This setting lets you override the maximum upload size for images (in bytes). If omitted, Wagtail will fall back to using its 10MB default value.
 
+(wagtailimages_max_image_pixels)=
+
 ### `WAGTAILIMAGES_MAX_IMAGE_PIXELS`
 
 ```python

docs/releases/4.1.md

@@ -96,6 +96,7 @@ There are multiple improvements to the documentation theme this release, here ar
  * Improvements to getting started tutorial aimed at developers who are very new to Python and have no Django experience (Damilola Oladele)
  * The `image_url` template tag, when using the serve view to redirect rather than serve directly, will now use temporary redirects with a cache header instead of permanent redirects (Jake Howard)
  * Add new test assertions to `WagtailPageTestCase` - `assertPageIsRoutable`, `assertPageIsRenderable`, `assertPageIsEditable`, `assertPageIsPreviewable` (Andy Babic)
+ * Add documentation to the performance section about how to better create image URLs when not used directly on the page (Jake Howard)
 
 ### Bug fixes