Grav ImgSrcset Plugin
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Grav Image Srcset Plugin

Adds a srcset-attribute to img-elements to allow for responsive images in Markdown. This allows modern browsers to load the image which best fits within the viewport, based on available images and sizes, essentially choosing the best image to reduce loading times (see RespImg).

Thus, on a small mobile screen this would load a much smaller image than on a large desktop. From this:

<img title="Street view from the east" alt="Street view" src="street.jpg">

To this:

<img title="Street view from the east" alt="Street view" src="street.jpg" srcset="street-320.jpg 320w, street-480.jpg 480w, street-640.jpg 640w, street-960.jpg 960w, street-1280.jpg 1280w, street-1600.jpg 1600w, street-1920.jpg 1920w, street-2240.jpg 2240w" sizes="100vw">

This is only applied to image-elements generated from Markdown. Depends on PHP Html Parser v1.7.0 for DOM parsing and manipulation of srcset and sizes.

Installation and Configuration

  1. Download the zip version of this repository and unzip it under /your/site/grav/user/plugins.
  2. Rename the folder to imgsrcset.

You should now have all the plugin files under


The plugin is enabled by default, and can be disabled by copying user/plugins/imgsrcset/imgsrcset.yaml into user/config/plugins/imgsrcset.yaml and setting enabled: false. For a simple Twig-integration see this gist.

Note: The plugin needs Twig to be processed first, so be sure to set twig_first to true in system.yaml, like this:

  twig_first: true

Generating images

This plugin does not leverage Grav's media caching mechanisms, it simply circumvenes the need for caching by assuming that images are generated outside of Grav. This is necessary because Grav currently uses the Gregwar library, which relies on PHP's GD-module for image manipulation, and it handles large or many images poorly - indeed it tends to crash both caching and Grav itself. Thus by creating the images outside of this system the same quality and automation is achieved.

For an example of generating responsive images with NodeJS and Gulp see this gist.


The widths setting is a YAML sequence wherein each integer represents the width of the image, defaulting to:

 - 320
 - 480
 - 640
 - 960
 - 1280
 - 1600
 - 1920
 - 2240


The sizes setting is a YAML string defining the sizes-attribute, defaulting to:

sizes: "100vw"


The plugin expects the images to be in the same folder as the source image. So, for the case of street.jpg, the page folder should contain:


MIT License 2017 by Ole Vik.