diff --git a/content/docs/api/db/record/thumbnail/contents.lr b/content/docs/api/db/record/thumbnail/contents.lr
index babd3849..3c4cd5d2 100644
--- a/content/docs/api/db/record/thumbnail/contents.lr
+++ b/content/docs/api/db/record/thumbnail/contents.lr
@@ -4,7 +4,7 @@ summary: Creates a thumbnail for an image.
---
type: method
---
-signature: width, height=None, crop=False, quality=None
+signature: width=None, height=None, mode=None, upscale=None, quality=None
---
body:
@@ -12,10 +12,25 @@ This method is available on attachments that are images and can be used to
automatically generate a thumbnail. The return value is a thumbnail proxy
that can be either used directly or with the `|url` filter.
-If cropping is not enabled the thumbnail is scaled down to fit into the
-given reactangle of width and height. If height is not specified it will
-match the width and the height is set accordingly. If cropping is enabled
-it's cropped around the edges to fit into the center.
+The outcome differs depending on the operation mode, which can be one of "fit"
+(the default), "crop" or "stretch".
+
+In "fit" mode, the thumbnail is scaled to fit into the rectangle of given
+width and height. If either dimension is `None`, it will be computed to match
+the other one accordingly.
+
+In "crop" mode, width and height are both required. The image is scaled
+to cover the given rectangle, center-aligned, and then cropped so that
+anything outside those bounds gets trimmed.
+
+In "stretch" mode, the image is resized precisely to the required dimensions,
+so the original proportions are not preserved. Most of the time this is not
+what you want.
+
+By setting the `upscale` parameter to `False` you can prevent the images
+from being scaled up if the resulting thumbnail would be larger than the original
+image. In this case the original is returned instead.
+(Note that in a future version this will be the default in "fit" mode.)
The quality parameter determines the compression of images where possible. If not passed the jpeg images get a default quality of 85 and png images get a default quality of 75.
@@ -26,9 +41,6 @@ It provides the following attributes:
* `url_path` the URL path of the thumbnail. This is absolute and needs to
be made relative with the `|url` filter.
-!!! Starting with Lektor 2.0 you can also pass `crop=True` to crop the image
-to the exact dimensions provided instead of scaling it uncropped.
-
## Example
```html+jinja
@@ -38,5 +50,11 @@ to the exact dimensions provided instead of scaling it uncropped.
```
```html+jinja
-
+{% for image in this.attachments.images %}
+
+{% endfor %}
+```
+
+```html+jinja
+
```
diff --git a/content/docs/api/utils/process-image/contents.lr b/content/docs/api/utils/process-image/contents.lr
index d5448b9b..5e3a1b6d 100644
--- a/content/docs/api/utils/process-image/contents.lr
+++ b/content/docs/api/utils/process-image/contents.lr
@@ -2,7 +2,7 @@ title: process_image
---
module: lektor.imagetools
---
-signature: ctx, source_image, dst_filename, width, height=None
+signature: ctx, source_image, dst_filename, width=None, height=None, mode=ThumbnailMode.DEFAULT
---
summary: Build an image from a source image, optionally compressing and resizing.
---
@@ -12,7 +12,11 @@ version_added: 2.0
---
body:
-This function takes a [Context :ref](../../build/context/) object, the absolute paths to the image's source and target files, and the target image's width. If height is `None`, it is calculated from the source image width and the target width so that the image is scaled proportionally.
+This function takes a [Context :ref](../../build/context/) object, the
+absolute paths to the image's source and target files, the target image's
+width and/or height, and the operation mode.
+In the default mode, if width or height are `None`, they are calculated
+from the source image's dimensions so that the image is scaled proportionally.
Used internally for the implementation of [thumbnail :ref](../../db/record/thumbnail), and exposed as an API for image-processing plugins.
@@ -22,24 +26,24 @@ Used internally for the implementation of [thumbnail :ref](../../db/record/thumb
from lektor.build_programs import AttachmentBuildProgram
from lektor.context import get_ctx
from lektor.db import Image
-from lektor.imagetools import process_image
+from lektor.imagetools import process_image, ThumbnailMode
from lektor.pluginsystem import Plugin
-class ResizeBuildProgram(AttachmentBuildProgram):
+class ImageCropBuildProgram(AttachmentBuildProgram):
def build_artifact(self, artifact):
ctx = get_ctx()
- width = 1024
+ width, height = 600, 400
source_img = artifact.source_obj.attachment_filename
artifact.ensure_dir()
process_image(ctx,
source_img,
artifact.dst_filename,
- width)
+ width, height, mode=ThumbnailMode.CROP)
-class ImageResizePlugin(Plugin):
+class ImageCropPlugin(Plugin):
def on_setup_env(self, **extra):
- self.env.add_build_program(Image, ResizeBuildProgram)
+ self.env.add_build_program(Image, ImageCropBuildProgram)
```
diff --git a/content/docs/templates/imageops/contents.lr b/content/docs/templates/imageops/contents.lr
index 642d9ec7..b224d855 100644
--- a/content/docs/templates/imageops/contents.lr
+++ b/content/docs/templates/imageops/contents.lr
@@ -81,8 +81,8 @@ still need to transmit the entire image. When you want smaller images it
often makes sense to generate thumbnails automatically. In Lektor each
image provides the [thumbnail :ref](../../api/db/record/thumbnail/) method.
-It accepts the width and height of the target image. If the height is not
-provided it will be scaled proportionally. The return value can be converted
+It accepts the width and height of the target image. If either of these is not
+provided, it will be computed automatically. The return value can be converted
into a URL with the `|url` filter:
```html+jinja