Documentation

Working with images Optimization, modern formats, sizes & DPI variants

The template automates the most common image tasks: compression for JPEG/PNG/GIF, conversion to WEBP/AVIF, generating multiple sizes for responsive images, and building 2x/3x variants for high-DPI screens. All controls live in template.config.js inside images → optimize.

What the build can do

  • Optimize (reduce size) for JPEG/JPG, PNG, GIF.
  • Convert images to modern formats: WEBP / AVIF.
  • Generate smaller versions for different screen widths (responsive images).
  • Generate bigger versions for high pixel density screens (DPI / 2x, 3x).
Where to control it
Open template.config.js → go to images → optimize and adjust options.

Enable / disable optimization

images → optimize → enable

Master switch for image optimization. If you plan to integrate with a backend that has its own image pipeline, you may want to disable the template-side processing.

  • true — images are processed (convert/resize/optimize based on your config).
  • false — images are copied “as is” (no conversion, no compression).

HTML rewriting

images → optimize → edithtml

Controls whether the build modifies HTML automatically (injecting <picture>, replacing file extensions after conversion, adding sources for sizes/DPI, etc.).

  • true — HTML is updated to match generated images.
  • false — HTML stays unchanged (useful if you write your own <picture> markup).
Tip
If you already have custom <picture> markup, either disable edithtml or use the ignore attribute described below.

Responsive sizes

images → optimize → sizes

Set the widths (in pixels) that should be generated for responsive output. Example: [600, 1200].

In dev you can write a simple image tag:

Dev markup
<img src="@img/cover.jpg" alt="Image">

After production build, it can be transformed into a <picture> with sources:

Build output example (sizes = [600, 1200])

<picture>
  <source media="(max-width: 600px)" srcset="./assets/img/cover-600.webp" type="image/webp">
  <source media="(max-width: 1200px)" srcset="./assets/img/cover-1200.webp" type="image/webp">
  <img alt="Image" src="./assets/img/cover.webp">
</picture>
Per-image custom sizes
You can override global sizes for one specific image using data-anim-image-sizes="1000, 600".
Per-image override
<img data-anim-image-sizes="1000, 600" src="..." alt="...">

High-DPI variants (2x, 3x)

images → optimize → dpi

Set DPI multipliers for screens with high pixel density. Example: [2, 3] to generate 2x and 3x versions.

Example output when sizes are enabled and DPI is [2, 3]:

Build output example (sizes + dpi)

<picture>
  <source
    media="(max-width: 600px)"
    srcset="
      ./assets/img/cover-600.webp 1x,
      ./assets/img/cover-600-2x.webp 2x,
      ./assets/img/cover-600-3x.webp 3x"
    type="image/webp">

  <source
    media="(max-width: 1200px)"
    srcset="
      ./assets/img/cover-1200.webp 1x,
      ./assets/img/cover-1200-2x.webp 2x,
      ./assets/img/cover-1200-3x.webp 3x"
    type="image/webp">

  <img
    alt="Image"
    src="./assets/img/cover.webp"
    srcset="
      ./assets/img/cover.webp 1x,
      ./assets/img/cover-2x.webp 2x,
      ./assets/img/cover-3x.webp 3x">
</picture>
Disable DPI generation
If you don’t want DPI variants, leave the array empty: [].

Ignore image processing

images → optimize → attrignore

Set the name of an attribute. If an <img> tag contains this attribute, the image processing for that tag is skipped.

When it’s useful
If you use your own <picture> in dev mode, you can mark the inner <img> to avoid automatic overrides, or disable global sizes.
Example ignore attribute on img
<img data-anim-image-sizes-ignore src="..." alt="...">

Modern formats: WEBP / AVIF

images → modernformat

Controls conversion to WEBP or AVIF. This can massively reduce image weight.

  • enable — enable conversion (true/false).
  • type — webp or avif.
  • only — if true, original files are removed; if false, originals can stay as fallbacks.
  • quality — 0–100 (higher = better quality, bigger file).

JPEG / PNG optimization quality

images → jpeg → quality

Controls compression quality for JPEG images (0–100). Higher means better quality but larger file size.

images → png → quality

Controls optimization quality for PNG images (0–100). Higher means better quality but larger file size.

Practical advice
Start with a “balanced” quality value and adjust after you check the visual result in your real pages.

Quick config checklist

template.config.js (images)

images: {
  svgsprite: true,
  optimize: {
    enable: true,
    edithtml: true,
    sizes: [600, 1200],
    dpi: [2, 3],
    attrignore: "data-anim-image-sizes-ignore"
  },
  modernformat: {
    enable: true,
    type: "webp",
    only: false,
    quality: 80
  },
  jpeg: { quality: 80 },
  png: { quality: 85 }
}
Remember
If optimization is disabled, images are copied without changes. If WordPress mode is enabled, this image optimization workflow is not applied.