Cloudinary Logo

Page load time is critical for any website and more so on when delivering to mobiles and portable devices. When I started using Hugo, I realised my images were stored on my shared web server, served in the wrong file format and not optimised for size or device.

This post will focus on a small change to your site - serving images from the cloud / content delivery network (CDN) using Cloudinary [referral]. This will make a big impact on page speed.

I’ll show you how to:

  1. Update your config.toml
  2. Change the source of images on the list post layout (a worked example)
  3. Master Cloudinary images
  4. Check your site performance
  5. What to check if it goes wrong

In a future post, I’ll cover the slightly more complex topic of dynamic images - different sizes for different devices and pixel resolution.

Setup a Cloudinary account and migrate content

First you’ll need to setup an account with Cloudinary - it’s free and for most uses, the free plan will work

If you have a large library of existing content, then you’ll want to upload your content to Cloudinary. Before you do, change the upload settings so that it preserves your existing filenames, otherwise by default the upload tool adds random characters to every uploaded content item. If you make this change, you should be able to just upload your entire image folder and not make any changes.

Update your config with Cloudinary

Open your config.toml and paste into the default params section

cloudinary_base_url ="<your username>”

Save the file and close it

Worked Example - Update your image source in your List layout

Every theme is different, but if your theme is like my blog, you’ll have a list of posts with an image with each item — you can see it on my blog

Open your Themes Folder - Layouts/_default/list.html and search for <img

Here’s the code that was originally there:

{{ with .Params.image }}<img src="{{ . }}" alt="post-image">{{ end }}

This looks for the image reference in the Front Matter of the post / blog markdown content and wraps it in the <img> tag

So the easy replacement is:

{{ with .Params.image }}<img src="{{ $.Site.Params.cloudinary_base_url }}/{{ . }}" alt="post-image"/>{{ end }}

This just looks for the same file - but from Cloudinary

Now save the file and go test … You’re serving up images from the cloud

Mastering Cloudinary Image controls

Cloudinary can do some great things to images … resize, crop, scale, face detection all on the fly and more

Here’s an original photo: Ella 2014

This code creates a 150x150 thumbnail automatically focusing on Ella’s face,h_150,c_thumb,g_face/blog/Ella_2014.jpg

Below is the best options to master image serving on Cloudinary


  • Width Auto w_auto
  • Centre Scale c_scale
  • Format Auto f_auto file format
  • Quality Auto q_auto
  • DPR Auto DPR_auto for retina display

Just open your Theme list.html file again and change the img tag to

{{ with .Params.image }}<img src="{{ $.Site.Params.cloudinary_base_url }}/w_auto,c_scale,f_auto,q_auto,dpr_auto/{{ . }}" alt="post-image"/>{{ end }}

Check your Site Performance

Actually if you haven’t done this already … head to Google PageSpeed Insights and baseline your site performance. Do check for Web and Mobile performance.

Then, after you publish your changes, go measure your sites performance again. It will be improved

Test and Go …

So now …

  1. Save the file
  2. Commit your changes to Git
  3. Run Hugo server -D and browse to http://Localhost to check every thing is work fine

If you find a problem

  • Check the page source - is the image src correct?
  • Check the config.toml params - did you add the URL in the default [params] section?

How did this work for you? Did you get a massive performance boost? Let me know


Tags: Performance, Cloudinary, Content Management

Read more from my blog for an introduction and quick tips on developing in Hugo or UCTD.