Responsive image on jekyll

3 minute read ~

Responsive image make your website faster by loading the image that is required for the screen. Loading high quality image in every screen size is not optimal. Also showing a low quality blur version of the image while the real image is loading also improve the readability.


jekyll-responsive-image plugin

First, add -

gem 'jekyll-responsive-image'

to your Gemfile.

Then add it to the plugins section of your _config.yml:

  - jekyll-paginate
  - jekyll-sitemap
  - jekyll-gist
  - jekyll-feed
  - jemoji
  - jekyll-archives
  - jekyll-responsive-image

Last, install the plugin by running

bundle install

Please Note: If there is an error while installing the plugin plese run sudo apt-get install libmagickwand-dev to install required library and try again. And if you are on windows follow this step How To Install The RMagick #RubyOnRails Gem on Windows 7 / 8 / 10 (ImageMagick 6.9.4 Q16-HDRI)


_config.yml file

Add those lines to the end of your _config.yml file-

# Responsive images
  # [Required]
  # Path to the image template.
  template: _includes/responsive-image.html

  # [Optional, Default: 85]
  # Quality to use when resizing images.
  default_quality: 90

  # [Optional, Default: []]
  # An array of resize configuration objects. Each object must contain at least
  # a `width` value.
    - width: 20 # lq
      quality: 10
    - width: 480  # [Required] How wide the resized image will be.
      quality: 80 # [Optional] Overrides default_quality for this size.
    - width: 800
    - width: 1400
      quality: 90

  # [Optional, Default: false]
  # Rotate resized images depending on their EXIF rotation attribute. Useful for
  # working with JPGs directly from digital cameras and smartphones
  auto_rotate: false

  # [Optional, Default: assets]
  # The base directory where assets are stored. This is used to determine the
  # `dirname` value in `output_path_format` below.
  base_path: assets/images

  # [Optional, Default: assets/resized/%{filename}-%{width}x%{height}.%{extension}]
  # The template used when generating filenames for resized images. Must be a
  # relative path.
  # Parameters available are:
  #   %{dirname}     Directory of the file relative to `base_path` (assets/sub/dir/some-file.jpg => sub/dir)
  #   %{basename}    Basename of the file (assets/some-file.jpg => some-file.jpg)
  #   %{filename}    Basename without the extension (assets/some-file.jpg => some-file)
  #   %{extension}   Extension of the file (assets/some-file.jpg => jpg)
  #   %{width}       Width of the resized image
  #   %{height}      Height of the resized image
  output_path_format: assets/images/resized/%{width}/%{basename}

  # [Optional, Default: true]
  # Whether or not to save the generated assets into the source folder.
  save_to_source: false

  # [Optional, Default: false]
  # Cache the result of {% responsive_image %} and {% responsive_image_block %} 
  # tags. See the "Caching" section of the README for more information.
  cache: false

  #/ [Optional, Default: []]
  # By default, only images referenced by the responsive_image and responsive_image_block
  # tags are resized. Here you can set a list of paths or path globs to resize other
  # images. This is useful for resizing images which will be referenced from stylesheets.
    - assets/foo/bar.png
    - assets/bgs/*.png
    - assets/avatars/*.{jpeg,jpg}

Create image template

Now create a responsive-image.html template file and paste the contents there-

{% capture srcset %}
{% for i in resized %}
    /{{ i.path }} {{ i.width }}w,
{% endfor %}
{% endcapture %}

{% assign smallest = resized | sort: 'width' | first %}

<img width="100%" src="/{{ smallest.path }}" alt="{{ alt }}" data-srcset="{{ srcset | strip_newlines }}" class="blur-up lazyautosizes lazyload"> 

Add lazysizes

You need to add lazysizes js file to your website. To do this, download the min version from here and put it to your assets/js folder and add those line to your script section depending on your theme.

  <script src="{{ '/assets/js/lazysizes.min.js'| absolute_url }}"></script> 

Please Note: I am using minimal mistake theme. So I added the js file in _includes>scripts.html after the main.min.js include code

CSS modification

Now add those line to your css file for blur effect for smoth image pixel

.no-js img.lazyload {
display: none;

.blur-up {
filter: blur(10px);
transition: filter 400ms;

.blur-up.lazyloaded {
filter: blur(0);

.fade-in {
opacity: 0;
transition: opacity 400ms;

.fade-in.lazyloaded {
opacity: 1;

How to use

To insert image in a post use

 {% responsive_image path: assets/images/Rio.jpg %} 

where assets/images/Rio.jpg is your image path. This will take care of everything. Now you can enjoy responsive image in your blog.


Here is a normal image- rio

and here is a responsive image with lazy loading enabled

Please Note: This may not work with Github Pages directly. You need to host your own jekyll site or use third party CI tool to build the site. I am using Travis ci for my blog. If you have any question feel free to ask me.

Leave a Comment