thumbnail (width=None, height=None, mode=None, upscale=None, quality=None)

From Lektor 2.0 to 3.1.2 cropping was set with crop=True. This is now deprecated and instead crop is an available mode, which can be set as mode=crop.

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.

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.

It provides the following attributes:

  • width: the thumbnail width in pixels.
  • height: the thumbnail height in pixels.
  • url_path the URL path of the thumbnail. This is absolute and needs to be made relative with the |url filter.


{% for image in this.attachments.images %}
  <img src="{{ image.thumbnail(64)|url }}">
{% endfor %}
{% for image in this.attachments.images %}
  <img src="{{ image.thumbnail(height=64)|url }}">
{% endfor %}
<img src="{{ image.thumbnail(1920, 1080, mode="crop", quality=40)|url }}">