Images

The image service produces responsive images via Pillow (optional, lazily imported — a text-only site pays nothing). Source images live under assets/ (or public/, or content/).

#Requirements

Pillow is only required when images are actually used:

  

    
        
    
    
    
        
            
                bash
            
        
        
            


        
        
            


            


        
    






  
pip install "epresso[images]"

If Pillow (or the source image) is unavailable, image() falls back to a plain <img> pointing at the original asset.

#image() — responsive <img>

  

    
        
    
    
    
        
            
                jinja
            
        
        
            


        
        
            


            


        
    






  
<img src="{{ image('photos/hero.jpg', widths=[400, 800, 1200], alt='Hero') }}">

Renders a WebP srcset with content-hashed filenames. Default widths are [400, 800, 1200]:

  

    
        
    
    
    
        
            
                html
            
        
        
            


        
        
            


            


        
    






  
<img src="/images/hero-<digest>-1200.webp" srcset="/images/hero-<digest>-1200.webp 1200w, ..." sizes="100vw" alt="Hero">

#picture() — WebP + JPEG fallback

picture() produces a <picture> with WebP sources plus a JPEG fallback — useful when you must support browsers without WebP:

  

    
        
    
    
    
        
            
                jinja
            
        
        
            


        
        
            


            


        
    






  
{{ picture('photos/hero.jpg', widths=[400, 800], alt='Hero') }}

#How it works

• _register(name, widths, formats) records processing jobs per source image.
• At build time, ImagePipeline.build(out_dir) resizes each source with LANCZOS to the requested widths and formats (webp and jpeg, quality 82).
• Outputs are written to dist/images/ with a content-hash digest in the filename; existing outputs are skipped (incremental/dev caching).
• Outputs are written under dist/images/<base>-<digest>-<width>.<ext>.

#SVG rasterization

SVG sources are rasterized to PNG first so Pillow can process them. epresso prefers cairosvg (needs the system cairo library); otherwise falls back to the inkscape or rsvg-convert CLI when available.

#Custom class

render_cls(name, widths, alt, cls, style="") is the class-aware variant (used by component image helpers) and renders an <img> with the given CSS class and optional inline style.