eleventy-plugin-embed-cloudinary

Write an image URL → get a responsive image.

Table of Contents

• What is this?
• Why?
• Installation
• Configuration
  • Required parameters
  • Options
  • Image version and image public ID

What is this?

This library is an Eleventy plugin that will let you write an image URL like this in your markdown...

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.

https://res.cloudinary.com/YOUR_CLOUDINARY_CLOUD_NAME/image/upload/YOUR_IMAGE_VERSION/YOUR_IMAGE_PUBLIC_ID.png

Maecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.

...and it will transform the image URL into a responsive image, optimized for your website visitor's device and browser:

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.</p>

<img
  alt="title of your image, retrieved automatically from Cloudinary at build time"
  class="CSS class/es to apply to all all <img> elements generated by this plugin"
  src="URL of the image hosted on your Cloudinary Media Library"
  srcset="comma-separated URLs of images transformed by Cloudinary (see details below)"
  sizes="media condition + comma-separated source size values (see details below)"
  width="width of your image, retrieved automatically from Cloudinary at build time"
  height="height of your image, retrieved automatically from Cloudinary at build time"
  loading="whether the image should be loaded using native lazy loading or not"
/>

<p>Maecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.</p>

Why?

Image optimization is hard and involves all of these steps:

1. serving the best available image format (e.g. AVIF, WebP) supported by your website visitors' browser.
2. picking the best resolution for each device used by your website visitors (you need to consider screen quality, Device Pixel Ratio, etc).
3. defining appropriate caching policies for your images (see Caching best practices & max-age gotchas).
4. optimizing your images for SEO and accessibility.
5. loading images lazily, not eagerly.

Even if you are a master of all of these things, it is still a lot of work. An image CDN like Cloudinary will take care of steps 1-3 (format, resolution, caching policies), so it will likely save you a lot of time. You just need to upload your highest resolution image to your Cloudinary Media Library and add alt and title metadata for SEO and accessibility.

Installation

Install the plugin with your package manager of choice (npm, yarn, pnpm).

npm i -D eleventy-plugin-embed-cloudinary

Add this plugin to your Eleventy configuration file (usually .eleventy.js):

const embedCloudinary = require('eleventy-plugin-embed-cloudinary');

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(embedCloudinary, {
    apiKey: 'YOUR_CLOUDINARY_API_KEY',
    apiSecret: 'YOUR_CLOUDINARY_API_SECRET',
    cloudName: 'YOUR_CLOUDINARY_CLOUD_NAME'
  });
};

Your API key and API secret are not exposed in the generated HTML. They are used to fetch the images hosted on your Cloudinary Media Library when Eleventy builds your site.

⚠️ Don't forget to set the Cloudinary API key, API secret and cloud name on your build server. For example, if your build runs on the Github CI, use GitHub secrets; if the build runs on Netlify, use Build environment variables.

Configuration

Required parameters

Parameter	Explanation
apiKey	Your Cloudinary API key.
apiSecret	Your Cloudinary API secret.
cloudName	Your Cloudinary cloud name.

Options

Option	Default	Explanation
cacheDirectory	.cache	Directory where the 11ty Cache (see eleventy-cache-assets) stores the responses from the Cloudinary API. It is strongly recommended that you add this folder to your .gitignore file.
cacheDuration	30m	How long a response stored in the 11ty Cache should be considered valid. For the syntax, see here.
classString	""	CSS class/es to apply to the generated <img> element.
shouldLazyLoad	true	Whether the generated <img> element should have the attribute loading="lazy" to instruct the browser to defer loading the image (browser support here).
shouldThrowOnMissingAlt	false	Whether this plugin should throw an error when fetching an image that does not have an alt attribute. See here how to add a Description (alt) to an image hosted on your Cloudinary Media Library.
shouldThrowOnMissingCaption	false	Whether this plugin should throw an error when fetching an image that does not have a caption attribute. See here how to add a Title (caption) to an image hosted on your Cloudinary Media Library.

Image version and image public ID

For each image URL you write in your markdown files, you will need to specify its public ID (it's the last part of the URL, without the file extension) and its version.

https://res.cloudinary.com/YOUR_CLOUDINARY_CLOUD_NAME/image/upload/YOUR_IMAGE_VERSION/YOUR_IMAGE_PUBLIC_ID.png