DOCSEARCHbyAlgolia
Submit Docs

Jekyll Picture Tag

repository·master·Indexed 20 days ago

https://github.com/rbuchberger/jekyll_picture_tag

A Jekyll plugin for automating responsive images, handling resizing, cropping, and format conversion (including WebP and AVIF). It generates complex HTML markup such as <picture> and <img> tags to support art direction and resolution switching via a simple {% picture %} Liquid tag and YAML configuration.

Tokens
19.4K
Snippets
91
Records
121
Agent score
63%

What's inside jekyll_picture_tag

  1. Overview of Jekyll Picture Tag

    master
    Jekyll Picture Tag is a tool for automating responsive images in Jekyll sites. It handles the generation of cropped, resized, and reformatted image files, and automatically produces the corresponding HTML markup. It is designed to solve both art direction (using different images for different screen sizes) and resolution switching (serving different sizes of the same image) problems through YAML configuration and a simple template tag.

  4. Choose a markup format for Jekyll Picture Tag

    master

    When using Jekyll Picture Tag, you can specify how the resulting HTML is structured using one of three markup format presets:

    1. picture: Generates a full <picture> element. This includes a <source> tag for every required srcset and a fallback <img> tag. Use this when you need complex responsive logic (e.g., different media queries or MIME types).
    2. img: Generates a single <img> tag that includes a srcset attribute. Use this for simpler responsive images where a single attribute is sufficient.
    3. auto: Automatically decides between an <img> tag and a <picture> tag. It will supply an <img> tag if you only have one srcset entry, otherwise it defaults to a <picture> tag.

  5. Use presets to configure JPT output

    master

    A preset is a collection of settings that determines the behavior of Jekyll Picture Tag (JPT), including the image formats used and the structure of the final HTML markup. You can specify a preset in the liquid tag to act as a blueprint for how JPT processes your images.

    If you omit the preset argument, JPT will use the default preset. In its simplest form, the default preset generates an <img> tag with a srcset attribute pointing to the newly generated images.

  6. Configure the `sizes` attribute for responsive images

    master

    The sizes attribute tells the browser how large an image will be on the screen at different breakpoints, allowing it to choose the correct source from the srcset before the page is fully rendered.

    In your _data/picture.yml preset, you map your defined media_queries to the expected display width.

    Important Notes:

    • You cannot use percentages (e.g., 50%) because the browser needs to know the size without calculating the parent container's width.
    • Use viewport units like vw or calc() (e.g., calc(100vw - 16px)).
    • If you do not provide sizes, the browser assumes the image is 100vw (full viewport width).
    • If you have a constant image size (like an icon), use the size key (e.g., size: 800px) instead of sizes to generate a pixel-ratio srcset.
    # Example configuration in _data/picture.yml
media_queries:
    mobile: 'max-width: 480px'
    tablet: 'max-width: 768px'

presets:
  default:
    sizes:
      mobile: calc(100vw - 16px)
      tablet: 80vw
    size: 800px

  7. Understand deployment challenges with Jekyll Picture Tag

    master

    Deploying a site using Jekyll Picture Tag (JPT) can be difficult because the plugin depends on system libraries (libvips and its dependencies) to generate images. Build environments vary significantly; a build that works locally may fail in a cloud container if specific image formats (like avif or jp2) require libraries that are not pre-installed.

    General Strategies:

    • Local Build + Upload: Building the site on your local machine and then uploading the generated _site folder to a hosting provider is the most reliable method, as it uses your local system's libraries.
    • Containerized Build: If using a service that pulls a git repository and builds it in a container (e.g., Netlify, AWS Amplify), you must verify that the container's environment supports your required image formats.

  8. Limitations of dimension_attributes

    master

    While dimension_attributes helps prevent layout jank, it has the following technical limitations:

    1. Art Direction: It does not work when using art direction (providing multiple different source images for different screen sizes). This is because the attributes can only be applied to the single <img> tag, and art direction relies on multiple <source> elements.
    2. Compatibility: It works for standard <img> tags and <picture> tags that offer multiple widths/formats, but only if they share the same aspect ratio logic applied to the single underlying <img> tag.

  9. Configure srcset types and widths

    master

    Depending on your image use case, you must configure widths differently:

    Width-based srcset (Responsive)

    Used for images that change size based on screen width.

    • Setting: widths:
    • Requirement: You must provide a sizes attribute in your Liquid tag.

    Pixel-ratio srcset (Fixed size)

    Used for images that stay the same size (e.g., avatars, icons) but need high-density support.

    • Settings: base_width: and pixel_ratios:

  10. Use smartcrop via the `keep` setting

    master

    Version 2.x replaces the old gravity setting with a Libvips-powered smartcrop feature called keep. This feature attempts to preserve the most interesting parts of an image.

    Replace your old gravity values (like north or southeast) with one of the following keep options:

    • attention (the default)
    • entropy
    • centre or center

    Note: Any crop geometry settings that are not in the w:h format should be removed.

  12. Create Subpresets using YAML merge keys

    master

    You can base a preset entirely on another by using the YAML merge key <<. This allows you to define a base preset and then create specialized presets that inherit all its properties while adding or overriding specific values.

    Important: Shallow Merging The merge operation is a shallow merge, not a deep merge. If you define a key in a subpreset that already exists in the base preset (such as attributes), the entire value of that key from the base preset will be overwritten by the new value. Nested properties within that key will not be merged; they will be replaced.

      base: &base
    formats: [webp, original]
    format_quality:
      webp: 90
    attributes:
      img: 'loading="lazy"'

  default:
    <<: *base
    widths: [500, 600, 700, 800, 900, 1000, 1200, 1600]
    link_source: true

  project_showcase:
    <<: *base
    widths: [700, 864, 900, 1296, 1600, 1728]