Publ: Image renditions

Last updated:

Image rendition support back to top

In entries back to top

See the entry format article

In templates back to top

Pass these in as parameters to entry.body and/or entry.more to configure the default values for entry images.

The template also gets a function, image(), that allows the template itself to render images.

Configuration values back to top

General configuration back to top

  • absolute: Whether to produce absolute URLs

  • link: Put a hyperlink on the image pointing to the given URL. Set this to False to prevent any links from being added, including from galleries.

  • link_class: What CSS class to apply to the image’s hyperlink

Style options back to top

  • img_class: If set, sets the class attribute on the image tag

  • img_style, style: A string or a list of strings, which provide inline CSS rules to the <img> element

    When the element is written, any attributes in style will override those in img_style; the intention is that in a Markdown tag, img_style comes from the container and style comes from the image.

  • shape: Adds the CSS3 shape-outline attribute to the image tag’s style; can be one of the following:

    • True: Uses the base rendition of the image itself (this is usually what you want)

    • A string value: uses the specified image’s alpha channel as the shape

      This can be any path scheme supported by the image path scheme (e.g. local-file.png, /common/absolute-file.png, @images/static-file.png, //

    For example, if you have an image inset-image.jpg that you want to mask off with inset-image-mask.png and float left, you can do:


    It is better to make image insets' float rules part of your stylesheet, however, so that it can be responsive; for example:


    The size of the outline image will be mapped the same as the base image, wherever possible; for example:


    will size both the image and its mask to fit within a 320x320 square.

Inline image sizing back to top

  • scale: What factor to scale the source image down by (e.g. 3 = the display size should be 33%)

  • scale_min_width: The minimum width to target based on scaling

  • scale_min_height: The minimum height to target based on scaling

  • width: The width to target

  • height: The height to target

  • max_width: If present and smaller than width, use this instead (useful for templates)

  • max_height: If present and smaller than height, use this instead (useful for templates)

  • resize: If both width and height are specified, how to fit the image into the rectangle if the aspect ratio doesn’t match

    • fit: Fit the image into the space (default)
    • fill: Fill the space with the image, cropping off the sides
    • stretch: Distort the image to fit
  • scale_filter: What scaling algorithm to use when resampling the image. Case-insensitive. See the Pillow documentation for more information on the available algorithms. Defaults to lanczos.

  • crop: Crops the thumbnail to the given rectangle, which is provided in the form of (x,y,w,h) or 'x,y,w,h', where x and y are the coordinates of the top-left corner and w and h are the size of the rectangle.

    The () notation is more flexible, but sometimes it doesn’t work; in that case, use the '' notation instead.

  • fill_crop_x: If resize="fill", where to take the cropping (0=left, 1=right); default=0.5

  • fill_crop_y: If resize="fill", where to take the cropping (0=top, 1=bottom); default=0.5

Note: Images will never be scaled to larger than their native resolution. (In the future there may be an option to still resize it larger client-side, where the actual rendition will be the native size but the <img> tag gets the expanded width and height.)

File format options back to top

  • format: Select the format to display the image as (defaults to the original format)

  • background: The background color to use when converting transparent images (such as .png) to non-transparent formats (such as .jpg).

    This parameter can be in a number of formats:

    • A named color such as "black" or "white"
    • An HTML-style hex code such as "#ff7733" or "#f73"
    • An RGB tuple such as (0,127,35) (note the lack of quotes!)

    If you’re daring you can also use any of the other color formats supported by PIL.ImageColor, e.g. "hsl(0,100%,50%)"

  • quality: The JPEG quality level to use for all renditions

  • quality_ldpi: The JPEG quality level to use for low-DPI renditions

  • quality_hdpi: The JPEG quality level to use for high-DPI renditions

Image set options back to top

These options drive the behavior of image sets.

  • div_class: The CSS class to use for the containing <div>

  • div_style: A string or a list of strings, which provide inline CSS rules to the <div> element

  • gallery_id: An identifier for the Lightbox image set (for use with lightbox.js)

    • Note: If this is not set, Lightbox will not be enabled, and popup renditions will not be generated
    • Note: If link is set, this option has no effect
  • count: How many images to allow in the image set (useful for feeds)

  • count_offset: If count is set, also skip this number of images at the beginning

  • fullsize_width: The maximum width for the popup image

  • fullsize_height: The maximum height for the popup image

  • fullsize_crop: The cropping rectangle for the full-sized image; see crop for the format.

  • fullsize_quality: The JPEG quality level to use for the popup image

  • fullsize_format: What format the popup image should be in (defaults to the original format)

  • fullsize_background: The background color to use when converting transparent images (such as .png) to non-transparent formats (such as .jpg)

  • more_text: If images were skipped due to count or count_offset, add this text after the image set. This string will be rendered with the following template arguments:

    • {count}: The total number of images in the image set
    • {remain}: The number of images not shown
  • more_link: If more_text is shown, it will be wrapped in a link with this location

  • more_class: If more_text is shown, it will be given this CSS class (either on the <a> tag if it’s a link, or via a <span>)

Template meta-options back to top

  • prefix: Specify one or more prefixes to check for additional rendition options.

    For example, if you have the following in your index.html:

    {{ entry.body(prefix='index_') }}

    then if you have an image like this:


    then on the page rendered via index.html it will be equivalent to:


    You can also specify multiple prefixes to check by putting them in a list, e.g.

    {{ entry.body(prefix=['index_','blog_']) }}

    In the case of multiple prefixes, the last one takes priority, so list them as least to most specific.

    This is probably only useful from a template file, rather than from an entry. Using a prefix on the prefix attribute itself (e.g. ![{index_prefix='foo_'}](me.jpg{foo_format='png'})) is undefined behavior and should probably make your head hurt to think about, and no it isn’t Turing-complete so don’t bother trying.

Useful template examples back to top

A webcomic back to top

index.html and entry.html:

This will treat source images as being 3x screen resolution, make images scale to no narrower than 480 pixels and to no wider than 960 pixels, encourage them to be a JPEG (with transparency turning white), and with 35% JPEG quality for the high-DPI rendition.

{{ entry.body(


This will resize the image to no more than 400 pixels wide or tall and crop the thumbnail to the top or left of the image (making for a useful non-punchline-destroying excerpt).

{{ entry.body(

In the above example, if you have a comic that is provided at screen resolution to begin with (such as guest art) you can override the default scaling with e.g.:

![](guest-comic.png{scale=1} "Amazing guest comic!")

Or if there’s one you want to force to a specific size:


which can also be written more compactly as:


With the below setup, if an entry provides an image set with a count_offset parameter, e.g.

![{count_offset=2}](image1.jpg | image2.jpg | image3.jpg | image4.jpg)

then on the index and feed (where there’s a count set) skip the first two images and thus show image3.jpg as the first image. This allows you to set a “poster” frame for the image set as a whole.

index.html back to top

This will show just the first image in the gallery at its original aspect, and then link the user to the full gallery page with an image count.

{{ entry.body(
    more_text='Show {count} images',

entry.html back to top

This will show the full gallery with square thumbnails and a reasonable default gallery ID, and the full images at 4K resolution. The thumbnails will be wrapped in a <div class="gallery_thumbs">.

{{ entry.body(

feed.xml back to top

This will show tiny thumbnails of the first three images of the gallery and will link to the full gallery page.

{{ entry.body(
    more_text='{remain} more images in gallery')