Home

Awesome

Jekyll Cloudinary Liquid tag

Build

<!-- [![Gem Version](https://badge.fury.io/rb/jekyll-cloudinary.svg)](https://badge.fury.io/rb/jekyll-cloudinary) [![Gem Downloads](https://img.shields.io/gem/dt/jekyll-cloudinary.svg?style=flat)](http://rubygems.org/gems/jekyll-cloudinary) -->

jekyll-cloudinary is a Jekyll plugin adding a Liquid tag to ease the use of Cloudinary for responsive images in your Markdown/Kramdown posts.

It builds the HTML for responsive images in the posts, using the srcset and sizes attributes for the <img /> tag (see the "varying size and density" section of this post if this is new for you, and why it's recommended to not use <picture> most of the time). URLs in the srcset are cloudinary URLs that fetch on-the-fly the post's images and resize them to several sizes.

You are in full control of the number of generated images and their sizes, and the sizes attribute that helps the browser decide which image to download. See the complete configuration options for details.

Here is the general syntax of this Liquid tag:

<!-- {% raw %} -->
{% cloudinary cloudflare.png alt="Un schéma montrant l'apport de Cloudflare" caption="Un schéma montrant l'apport de Cloudflare" loading="lazy" %}
<!-- {% endraw %} --> <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Installation

Sign up for free on Cloudinary! The free account should be enough for most blogs.

Add gem 'jekyll-cloudinary' to the jekyll_plugin group in your Gemfile:

source 'https://rubygems.org'

gem 'jekyll'

group :jekyll_plugins do
  gem 'jekyll-cloudinary'
end

Then run bundle to install the gem.

Configuration

Mandatory settings

Add cloudinary to your _config.yml and your Cloudinary "Cloud name" (find it in your Cloudinary dashboard):

cloudinary:
  cloud_name: <put here your Cloudinary "Cloud name">

Optional global settings

You can now define some global settings

cloudinary:
  …
  only_prod: true
  verbose: true
  origin_url: https://another-domain.com

only_prod (default: false)

When set to true, this setting implies that responsive image HTML and Cloudinary URLs are generated only if the environment is production.

For example:

JEKYLL_ENV=development is the default value.

If you don't set only_prod or set it to false, responsive image HTML and Cloudinary URLs are always generated, whatever the environment. jekyll-cloudinary had only this behavior before version 1.11.0.

verbose (default: false)

When set to true, this setting will show messages in the console when something goes wrong, such as:

[Cloudinary] Couldn't find this image to check its width: /path/to/jekyll/_site/assets/img.jpg

or

[Cloudinary] Natural width of source image 'img.jpg' (720px) in _posts/2016-06-09-post.md not enough for creating 1600px version

origin_url

When origin_url is set, jekyll-cloudinary will use this URL rather than site.url as origin of the source images.

This allows you to store your source image on a different domain than your website.

Optional (but highly recommended) presets

You can now define the presets you need for your posts' images, starting with the default one:

Default preset

The default preset is the one you don't even have to mention when using the Liquid tag, and that will be used if a preset you use in the tag doesn't exist.

cloudinary:
  …
  presets:
    default:
      min_width: 320
      max_width: 1600
      fallback_max_width: 800
      steps: 5
      sizes: "(min-width: 50rem) 50rem, 90vw"

This preset will generate five images 320 to 1600 pixels wide in the srcset and define sizes as "(min-width: 50rem) 50rem, 90vw". The fallback image defined in the src will have a width of 800 pixels.

With this preset, you only have to write this in your Markdown post:

<!-- {% raw %} -->
{% cloudinary /assets/img.jpg alt="beautiful!" %}
<!-- {% endraw %} -->

To get this HTML:

<img
  src="http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_800,q_auto,f_auto/https://<your-domain>/assets/img.jpg"
  srcset="
    http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_320,q_auto,f_auto/https://<your-domain>/assets/img.jpg 320w,
    http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_640,q_auto,f_auto/https://<your-domain>/assets/img.jpg 640w
    http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_960,q_auto,f_auto/https://<your-domain>/assets/img.jpg 960w
    http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_1280,q_auto,f_auto/https://<your-domain>/assets/img.jpg 1280w
    http://res.cloudinary.com/<cloud_name>/image/fetch/c_limit,w_1600,q_auto,f_auto/https://<your-domain>/assets/img.jpg 1600w
    "
  sizes="(min-width: 50rem) 50rem, 90vw"
  alt="beautiful!"
  width="480"
  height="320"
/>

There is a true default default preset, but you're strongly encouraged to override it with your own default preset.

Additional presets

You can add other presets if you need several image sizes in your posts.

Here is an example for images that take only one third of the post width:

cloudinary:
  …
  presets:
    …
    onethird:
      min_width: 110
      max_width: 535
      fallback_max_width: 300
      steps: 3
      sizes: "(min-width: 50rem) 17rem, 30vw"
      attributes:
        class: "one3rd"
        loading: "lazy"

To use this additional preset, you will have to write this in your Markdown post:

<!-- {% raw %} -->
{% cloudinary onethird /assets/img.jpg %}
<!-- {% endraw %} -->

The generated element will also get a class="one3rd" that can be useful for example with this CSS:

.one3rd {
  max-width: 33%;
  float: right;
  margin: 0 0 1em 1em;
}

Detailed preset settings

figure (default: auto)

This setting lets you decide what to do when there is a caption attribute in the Cloudinary Liquid tag.

The value can be:

If a <figure> is generated and there are attributes (in the preset or the Liquid tag), they are added to the <img> if they are alt, title or loading, or to the <figure>.

min_width (default: 320)

max_width (default: 1200)

fallback_max_width (defaut: 1200)

steps (default: 5)

sizes (default: "100vw")

attributes (default: none)

You can define attributes that will be added to all images using this preset. Attributes are added without transformation to the generated element.

You should obviously not add to preset attributes that should have different values for each image, such as alt, caption, title, etc.

You can set a class, aria-* attributes for enhanced accessibility, or even data-* attributes you would like to use later with CSS or JavaScript.

Liquid tag values

You can use liquid variables inside the liquid tag.

For example, if you have the picture path in a thumbnail attribute of the YAML Front Matter, you can use it in the tag:

<!-- {% raw %} -->
{% cloudinary {{ page.thumbnail }} alt="{{ page.title }} image" %}
<!-- {% endraw %} -->

Liquid tag attributes

You can add attributes to the liquid tag, after the image path:

<!-- {% raw %} -->
{% cloudinary onethird /assets/selfie.jpg alt="My selfie" loading="eager" %}
<!-- {% endraw %} -->

Just like the ones from the preset settings, inline attributes are added without transformation to the generated element.

Recommended attributes

You should obviously define the alt attribute, mandatory for accessibility.

If you want the image to be inside a figure element, you probably also want to add a caption attribute. This is the only one that can act differently than other attributes, depending on the figure setting.

You can also set a title attribute, but there are really few use cases for it on images.

alt, caption and title attributes can contain Markdown.

Loading attribute

The loading attribute allows you to tell the browser how you want it to load this image.

From this article written by Addy Osmani:

The loading attribute allows a browser to defer loading offscreen images and iframes until users scroll near them. loading supports three values:

Not specifying the attribute at all will have the same impact as setting loading=auto.

Other interesting attributes

You can also use attributes to add a class, aria-* attributes for enhanced accessibility, or even data-* attributes you would like to use later with CSS or JavaScript.

Live example

Go to this post: https://nicolas-hoizey.com/2016/07/tout-change-rien-ne-change.html.

The source Markdown is here: https://github.com/nhoizey/nicolas-hoizey.com/blob/master/_posts/2016/07/13-tout-change-rien-ne-change/2016-07-13-tout-change-rien-ne-change.md.

The content is in french, yes, but look only at the images if you don't understand.

You'll find here:

These image types need different settings to deal with different sizes and position:

This is how I use the Cloudinary Liquid tag for the Cloudinary logo and prices table screenshot:

<!-- {% raw %} -->
{% cloudinary logo /assets/logos/cloudinary.png alt="Logo de Cloudinary" %}
{% cloudinary cloudinary-pricing.png alt="Les tarifs de Cloudinary" caption="Les tarifs de Cloudinary, dont l'offre gratuite déjà généreuse" %}
<!-- {% endraw %} -->

The only difference is that I explicitly use the logo preset for the logo. The other image uses the default preset.

Here is the necessary configuration for this:

cloudinary:
  cloud_name: …
  verbose: false
  presets:
    default:
      min_width: 320
      max_width: 1600
      fallback_max_width: 800
      steps: 5
      sizes: '(min-width: 50rem) 50rem, 90vw'
      figure: always
    logo:
      min_width: 80
      max_width: 400
      fallback_max_width: 200
      steps: 3
      sizes: '(min-width: 50rem) 13rem, (min-width: 40rem) 25vw, 45vw'
      figure: never
      attributes:
        class: logo

It generates these HTML fragments (pretty printed here), for the logo:

<img
  src="https://res.cloudinary.com/nho/image/fetch/c_limit,w_200,q_auto,f_auto/https://nicolas-hoizey.com/assets/logos/cloudinary.png"
  srcset="
    https://res.cloudinary.com/nho/image/fetch/c_limit,w_80,q_auto,f_auto/https://nicolas-hoizey.com/assets/logos/cloudinary.png 80w,
    https://res.cloudinary.com/nho/image/fetch/c_limit,w_240,q_auto,f_auto/https://nicolas-hoizey.com/assets/logos/cloudinary.png 240w,
    https://res.cloudinary.com/nho/image/fetch/c_limit,w_400,q_auto,f_auto/https://nicolas-hoizey.com/assets/logos/cloudinary.png 400w"
  sizes="
    (min-width: 50rem) 13rem,
    (min-width: 40rem) 25vw,
    45vw"
  class="logo"
  alt="Logo de Cloudinary"
  width="480"
  height="350"
/>

And for the screenshot:

<figure>
  <img
    src="https://res.cloudinary.com/nho/image/fetch/c_limit,w_800,q_auto,f_auto/https://nicolas-hoizey.com/2016/07/cloudinary-pricing.png"
    srcset="
      https://res.cloudinary.com/nho/image/fetch/c_limit,w_320,q_auto,f_auto/https://nicolas-hoizey.com/2016/07/cloudinary-pricing.png 320w,
      https://res.cloudinary.com/nho/image/fetch/c_limit,w_640,q_auto,f_auto/https://nicolas-hoizey.com/2016/07/cloudinary-pricing.png 640w,
      https://res.cloudinary.com/nho/image/fetch/c_limit,w_960,q_auto,f_auto/https://nicolas-hoizey.com/2016/07/cloudinary-pricing.png 960w,
      https://res.cloudinary.com/nho/image/fetch/c_limit,w_1208,q_auto,f_auto/https://nicolas-hoizey.com/2016/07/cloudinary-pricing.png 1208w"
    sizes="(min-width: 50rem) 50rem, 90vw"
    alt="Les tarifs de Cloudinary"
    width="1208"
    height="561"
  />
  <figcaption>Les tarifs de Cloudinary, dont l'offre gratuite déjà généreuse</figcaption>
</figure>

There are only 4 version in the srcset here because 2 of the 5 expected sizes are larger than the source image, and are replaced by one using the native source image width.

And here are the relevant parts of the accompanying CSS (in Sass form):

article {
  figure, img {
    margin: 2em auto;
    display: block;
    max-width: 100%;
    height: auto;
  }
}

.logo {
  display: block;
  margin: 1em auto;
  max-width: 50%;
  height: auto;

  @media (min-width: 40em) {
    max-width: 25%;
    float: right;
    margin: 0 0 1em 1em;
  }
}

Contributing

Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here.

Do you use the plugin on a live site?

Add it to the "Sites" page of the wiki and please let us know on Twitter: @mavaddat @nhoizey