# Publ: Image renditions

Last updated:

## Image rendition support

### In entries

See the entry format article

### In templates

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

### General configuration

• absolute: Whether to produce absolute URLs

• link: Put a hyperlink on the image pointing to the given URL

### Style options

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

If both are set, class wins; the intention is that in a Markdown context, img_class comes from the container and class comes from the image.

• 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, //example.com/remote-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:

![](inset-image.jpg{shape="inset-mask.png",style="float:left"})

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

![](inset-image.jpg{shape="inset-mask.png",img_class="inset-left"})

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

![{320,320}](inset-image.jpg{shape="inset-mask.png"})

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

### Inline image sizing

• 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
• 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

• 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

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

• 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:

![](me.jpg{crop='5,5,500,400',index_crop='20,20,400,300'})

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

![](me.jpg{crop='20,20,400,300'})

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

### A webcomic

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, force them to be a JPEG (with transparency turning white), and with 35% JPEG quality for the high-DPI rendition

{{ entry.body(
scale=3,
scale_min_width=480
width=960,
format="jpg",
background="white",
quality_hdpi=35)
}}


feed.xml:

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(link=entry.link(
absolute=True,
force_width=400,
force_height=400,
resize="fill",
fill_crop_x=0,
fill_crop_y=0,
force_size=True)
}}


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:

![](special-comic.jpg{width=960,height=480})

which can also be written more compactly as:

![](special-comic.jpg{960,480})

### A photo gallery

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

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(
width=640,
height=640,
count=1,
more_text='Show {count} images',
}}


#### entry.html

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(
width=640,
height=640,
resize="fill",
lightbox_id=entry.uuid,
div_class="gallery_thumbs",
fullsize_width=3840,
fullsize_height=2160)
}}


#### feed.xml

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

{{ entry.body(
max_width=300,
max_height=300,
count=3,