Cecil logo Cecil
Cecil logo Cecil
What's on this page

Images

Cecil provides Twig functions and filters to resize, crop and convert images, and to generate responsive images and placeholders.

image_srcset

Builds the HTML img srcset (responsive) attribute of an image asset.

{{ image_srcset(asset) }}

Example:

{% set asset = asset(image_path) %}
<img src="{{ url(asset) }}" width="{{ asset.width }}" height="{{ asset.height }}" alt="" class="asset" srcset="{{ image_srcset(asset) }}" sizes="{{ image_sizes('asset') }}">

image_sizes

Returns the HTML img sizes attribute based on a CSS class name (see assets.images.responsive.sizes).

It should be used in conjunction with the image_srcset function (see the example above).

{{ image_sizes('class') }}

image_from_website

Builds the HTML img element from a website URL by extracting its illustration image. Returns null if no image is found.

{{ image_from_website('url', {attributes}, {options}) }}

Candidates are searched in the page HTML in the following order; the first one that can be downloaded as an image is used:

  1. Open Graph: og:image:secure_url, og:image, og:image:url
  2. Twitter: twitter:image, twitter:image:src
  3. <link rel="image_src">
  4. Microdata: itemprop="image"
  5. JSON-LD: image property
  6. First <img> of <article>, <main> or <body>
  7. <link rel="apple-touch-icon">
  8. <link rel="icon">

Relative URLs are resolved against <base href> or the page URL.

The resolved image URL and the downloaded image are cached (see cache.assets.remote.ttl).

Options:

  • fallback: image path (or URL) used if no image is found
  • other image options (e.g.: responsive, formats)

Examples:

{{ image_from_website('https://example.com/page-with-image.html') }}

{# with a fallback image #}
{{ image_from_website('https://example.com/', {alt: 'Illustration'}, {fallback: 'images/default.png'}) }}

resize

Resizes an image to a specified width (in pixels) and/or height (in pixels).

  • If only the width is specified, the height is calculated to preserve the aspect ratio
  • If only the height is specified, the width is calculated to preserve the aspect ratio
  • If both width and height are specified, the image is resized to fit within the given dimensions, then cropped and centered if necessary
  • If remove_animation is true, any animation in the image (e.g.: GIF) is removed
{{ asset(image_path)|resize(width: width, height: height, remove_animation: bool) }}

Examples:

{{ asset(page.image)|resize(300) }}
{# equivalent to: #}
{{ asset(page.image)|resize(width: 300) }}
{# resizes to 200px height, width auto-calculated to preserve aspect ratio #}
{{ asset(page.image)|resize(height: 200) }}
{# resizes to 300px width and 200px height, and crops if necessary #}
{{ asset(page.image)|resize(300, 200) }}
{# removes any animation from the image #}
{{ asset(page.image)|resize(width: 1200, height: 630, remove_animation: true) }}

cover

Resizes an image to a specified width and height, cropping it if necessary.

{{ asset(image_path)|cover(width, height) }}

Example:

{{ asset(page.image)|cover(1200, 630) }}

maskable

Adds padding, as a percentage of the image size (20 by default), to an image to make it maskable.

{{ asset(image_path)|maskable(padding) }}

Example:

{{ asset('icon.png')|maskable }}

webp

Converts an image to WebP format, with an optional quality (default: assets.images.quality).

{{ asset(image_path)|webp(quality) }}

Example:

<picture>
    <source type="image/webp" srcset="{{ asset(image_path)|webp }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

avif

Converts an image to AVIF format, with an optional quality (default: assets.images.quality).

{{ asset(image_path)|avif(quality) }}

Example:

<picture>
    <source type="image/avif" srcset="{{ asset(image_path)|avif(60) }}">
    <img src="{{ url(asset(image_path)) }}" width="{{ asset(image_path).width }}" height="{{ asset(image_path).height }}" alt="">
</picture>

lqip

Returns a Low Quality Image Placeholder (100 px wide, blurred) as data URL.

{{ asset(image_path)|lqip }}

dominant_color

Returns the dominant color of an image, as a CSS color value (e.g. rgb(120 85 60)).

{{ asset(image_path)|dominant_color }}
View as Markdown
Suggest a modification
← Assets CSS, JavaScript and processing →