Smart Image Bundles

Smart Image Bundles create a <picture> element for supported variants in an .img directory. They select color scheme first, then resolution, then image format.

Image directory

Name the directory with an .img suffix.
Use light, dark, or image as the base name.
Add @2x or @3x before the extension for higher-density images.
Supported formats, in preference order: SVG, AVIF, HEIC, WebP, APNG, PNG, JPEG (.jpg), GIF, and BMP.

The following directory contains neutral images only:

Chart.img/
    image.jpg
    image.webp
    image@2x.jpg

Reference a variant in Markdown. The exact referenced file remains the fallback <img> image:

![Chart](Chart.img/image.jpg)

Use both light and dark for color-scheme-specific images:

Chart.img/
    light.avif
    dark.avif

You can combine neutral and color-scheme-specific images. Reference image.* when the neutral image should be the fallback for browsers without a matching color preference:

Chart.img/
    image.jpg
    image.webp
    image.avif
    image@2x.jpg
    light.jpg
    dark.jpg

![Chart](Chart.img/image.jpg)

If the Markdown instead references light.* or dark.*, image.* variants are ignored.

Selection order

MarkShup emits sources in this order:

The matching light or dark group, when both groups exist.
The fallback group: image when Markdown references image.*; otherwise the referenced light or dark group.
Within each group: @3x, @2x, then 1x.
Within each resolution: the supported format with the highest preference.
The exact Markdown reference as the fallback <img src>.

For the combined example above, a dark preference selects dark.jpg, a light preference selects light.jpg, and no matching preference selects image@2x.jpg on a 2x display. At 1x, it selects AVIF, then WebP, then the referenced JPEG as browser support permits.

@2x and @3x images render at the same CSS size as their 1x equivalent. They target approximately 144 dpi and 216 dpi displays.

Alt text

Add an alt.txt file to override the Markdown image label:

Chart.img/
    alt.txt
    image.jpg

Disabling detection

Use --no-detect-img to treat .img directories as ordinary directories. A Markdown-referenced file inside an .img directory is still copied and emitted as a normal <img> element. Other variants are not discovered or copied. Smart Image Bundle detection is enabled by default; --detect-img restores it in a later template override.