By Jordan M. Ellis, March 10, 2026

Asset Guru

In today’s digital world, managing and serving assets efficiently is crucial for online platforms, especially those heavily reliant on multimedia content. This piece will delve into the integration of Cloudinary with the Hugo static site generator, focusing on serving assets effectively while ensuring that the workflow for content editors remains streamlined and productive.

This article follows up on the previous discussion regarding “Editor-Friendly Image Transformation and Optimized Delivery With Cloudinary and Decap CMS.” Here, we will expand on how to serve dynamic and responsive images through Hugo, leveraging the power of Cloudinary for asset management. If you have not set up your environment with Hugo, Decap, and Cloudinary yet, I highly recommend following the setup guide in the previous article to get started.

Understanding the Limitations of Traditional Asset Storage

While Hugo offers robust capabilities for handling images, especially through its built-in image processing functions, storing images directly in a version-controlled Git repository can present significant challenges. Platforms like GitHub impose limitations on file sizes, rendering the storage of high-resolution images impractical. Although options like Git Large File Storage (LFS) exist, they often complicate the developer experience.

A far better approach is to utilize a digital asset manager (DAM), with Cloudinary being a prime example. Cloudinary not only supports the storing of images but also offers powerful tools for transforming and delivering these assets efficiently. By utilizing their infrastructure, you can streamline your workflows, ensuring quick load times and improved performance for your users.

Setting Up Hugo Layouts for Image Management

Let us begin by setting up a minimal Hugo project focusing on rendering blog posts, especially the image partial. This section will guide you through creating a basic layout and integrating an image component into your posts.

layouts/_default/single.html     
 
{{ .Title }}
 {{ partial "image" (dict "src" .Params.image "alt" .Title) }} {{ .Content }} 

Before proceeding, ensure you create the image partial as illustrated below. We will refine this in subsequent sections.

layouts/partials/image.html

Next, let’s define a sample blog post by creating a markdown file.

content/blog/post.md---title: Post Titleimage: https://res.cloudinary.com/poslovnimediji/image/upload/sample.jpg---This is an example of markdown content.

After completing these steps, start your Hugo server with the command hugo server. You should access your local site and verify that the page loads correctly, displaying your title, image, and content at http://localhost:1313/blog/post/.

Utilizing Cloudinary’s URL Structures

Cloudinary offers a range of URLs for asset management, providing options for both unaltered and transformed images. Understanding how to navigate these URL formats is essential for effective image delivery.

Working with Filenames

For images stored in Cloudinary, you may only receive the asset ID in the front matter of your content. To use this effectively, you should configure the hugo.toml file. This file will allow you to establish a domain and default transformations that apply to your assets.

hugo.toml[params][params.cld]url = "https://res.cloudinary.com/poslovnimediji/image/upload/"transform = "c_fill,w_auto,g_auto,q_auto,dpr_auto/f_auto"

This configuration allows us to adjust our image partial to include necessary transformations:

layouts/partials/image.html

Note that using filenames might not provide the necessary folder structure; you will need to hardcode this to ensure the images are referenced correctly. Editors can still select assets from various folders within Cloudinary.

Handling URLs Without Transformations

If you prefer to utilize URLs without transformations, you will receive predefined folder information. However, default transformations must still be appended to the URL to maintain consistency.

layouts/partials/image.html{{ $cldUrl := site.Params.cld.url }}{{ $cldTransform := site.Params.cld.transform }}{{ $src := .src }}{{ if hasPrefix $src $cldUrl }} {{ $assetId := replace $src $cldUrl "" }} {{ $src = print $cldUrl $cldTransform "/" $assetId }}{{ end }}

Alternatively, using the default_transformations in your Decap configuration can simplify this process by applying universal transformations globally. However, be cautious, as changing the default may require adjustments to all asset URLs in your content.

Creating Responsive Images Using Cloudinary

By integrating Cloudinary’s JavaScript library, specifically cloudinary-core-shrinkwrap.js, you can manage responsive images easily. This library automatically adjusts the width of images based on the container’s size.

Add the following script to your Hugo template just before the closing body tag to incorporate the Cloudinary library.

layouts/_default/single.html

Modify your image partial to include the cld-responsive class and switch the src attribute to data-src for optimal functionality.

layouts/partials/image.html

For additional guidance on utilizing responsive images, refer to Cloudinary’s documentation that covers the JavaScript library in detail.

Implementing Mobile and Desktop Images

A practical implementation is serving different images for mobile and desktop displays, allowing editors to define both versions. This can be efficiently handled through the same image partial.

layouts/partials/image.html{{ $cldUrl := site.Params.cld.url }}{{ $cldTransform := site.Params.cld.transform }}{{ $src := .src }}{{ $srcDesktop := .srcDesktop }}{{ if hasPrefix $src $cldUrl }} {{ $assetId := replace $src $cldUrl "" }} {{ $src = print $cldUrl $cldTransform "/" $assetId }}{{ end }}{{ if hasPrefix $srcDesktop $cldUrl }} {{ $assetIdDesktop := replace $srcDesktop $cldUrl "" }} {{ $srcDesktop = print $cldUrl $cldTransform "/" $assetIdDesktop }}{{ end }} {{ if $srcDesktop }}  {{ end }} 

Conclusion

This exploration has provided insights into various methods for serving Cloudinary assets with Hugo. By combining approaches, such as providing separate images for mobile and desktop screens while employing the responsive class, you can optimize asset delivery and ensure an enhanced user experience.

Managing digital assets effectively is paramount in creating stunning and adaptable websites. With Cloudinary, you can streamline your image management process, ensuring optimal display across all devices. For more information and to start implementing these techniques in your projects, consider exploring the resources at Asset Guru.