{"id":15022938,"url":"https://github.com/jackdbd/eleventy-plugin-embed-cloudinary","last_synced_at":"2026-02-13T08:54:05.266Z","repository":{"id":38190897,"uuid":"367115604","full_name":"jackdbd/eleventy-plugin-embed-cloudinary","owner":"jackdbd","description":"Eleventy plugin to automatically embed images hosted on your Cloudinary Media Library.","archived":false,"fork":false,"pushed_at":"2022-06-09T18:00:35.000Z","size":1176,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-30T00:35:57.540Z","etag":null,"topics":["11ty","cloudinary","eleventy","eleventy-plugin","image"],"latest_commit_sha":null,"homepage":"https://jackdbd.github.io/eleventy-plugin-embed-cloudinary/index.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackdbd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-13T16:54:07.000Z","updated_at":"2022-11-06T20:38:10.000Z","dependencies_parsed_at":"2022-08-19T05:30:52.653Z","dependency_job_id":null,"html_url":"https://github.com/jackdbd/eleventy-plugin-embed-cloudinary","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Feleventy-plugin-embed-cloudinary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Feleventy-plugin-embed-cloudinary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Feleventy-plugin-embed-cloudinary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackdbd%2Feleventy-plugin-embed-cloudinary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackdbd","download_url":"https://codeload.github.com/jackdbd/eleventy-plugin-embed-cloudinary/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142043,"owners_count":20890652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["11ty","cloudinary","eleventy","eleventy-plugin","image"],"created_at":"2024-09-24T19:58:33.428Z","updated_at":"2025-10-05T14:17:51.336Z","avatar_url":"https://github.com/jackdbd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eleventy-plugin-embed-cloudinary\n\n[![npm version](https://badge.fury.io/js/eleventy-plugin-embed-cloudinary.svg)](https://badge.fury.io/js/eleventy-plugin-embed-cloudinary) ![Snyk Vulnerabilities for npm package](https://img.shields.io/snyk/vulnerabilities/npm/eleventy-plugin-embed-cloudinary) ![ci workflow](https://github.com/jackdbd/eleventy-plugin-embed-cloudinary/actions/workflows/ci.yml/badge.svg) [![codecov](https://codecov.io/gh/jackdbd/eleventy-plugin-embed-cloudinary/branch/main/graph/badge.svg?token=evryHx64zZ)](https://codecov.io/gh/jackdbd/eleventy-plugin-embed-cloudinary) [![CodeFactor](https://www.codefactor.io/repository/github/jackdbd/eleventy-plugin-embed-cloudinary/badge)](https://www.codefactor.io/repository/github/jackdbd/eleventy-plugin-embed-cloudinary) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=jackdbd_eleventy-plugin-embed-cloudinary\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=jackdbd_eleventy-plugin-embed-cloudinary)\n\nWrite an image URL → get a responsive image.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\u003cdetails\u003e\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [What is this?](#what-is-this)\n- [Why?](#why)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [Required parameters](#required-parameters)\n  - [Options](#options)\n  - [Image version and image public ID](#image-version-and-image-public-id)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c/details\u003e\n\n## What is this?\n\nThis library is an [Eleventy plugin](https://www.11ty.dev/docs/plugins/) that will let you write an **image URL** like this in your markdown...\n\n```markdown\nLorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.\n\nhttps://res.cloudinary.com/YOUR_CLOUDINARY_CLOUD_NAME/image/upload/YOUR_IMAGE_VERSION/YOUR_IMAGE_PUBLIC_ID.png\n\nMaecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.\n```\n\n...and it will transform the image URL into a [responsive image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images), optimized for your website visitor's device and browser:\n\n```html\n\u003cp\u003eLorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.\u003c/p\u003e\n\n\u003cimg\n  alt=\"title of your image, retrieved automatically from Cloudinary at build time\"\n  class=\"CSS class/es to apply to all all \u003cimg\u003e elements generated by this plugin\"\n  src=\"URL of the image hosted on your Cloudinary Media Library\"\n  srcset=\"comma-separated URLs of images transformed by Cloudinary (see details below)\"\n  sizes=\"media condition + comma-separated source size values (see details below)\"\n  width=\"width of your image, retrieved automatically from Cloudinary at build time\"\n  height=\"height of your image, retrieved automatically from Cloudinary at build time\"\n  loading=\"whether the image should be loaded using native lazy loading or not\"\n/\u003e\n\n\u003cp\u003eMaecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.\u003c/p\u003e\n```\n\n## Why?\n\nImage optimization is [hard](https://web.dev/fast/#optimize-your-images) and involves all of these steps:\n\n1. serving the best available **image format** (e.g. [AVIF](https://caniuse.com/?search=AVIF), [WebP](https://caniuse.com/?search=WebP)) supported by your website visitors' browser.\n2. picking the best **resolution** for each device used by your website visitors (you need to consider [screen quality, Device Pixel Ratio, etc](https://archive.fosdem.org/2021/schedule/event/webperf_making_rum_responsive/)).\n3. defining appropriate **caching policies** for your images (see [Caching best practices \u0026 max-age gotchas](https://jakearchibald.com/2016/caching-best-practices/)).\n4. optimizing your images for **SEO** and **accessibility**.\n5. loading images **lazily**, not eagerly.\n\nEven if you are a master of all of these things, it is still a lot of work. An [image CDN](https://web.dev/image-cdns/) 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.\n\n## Installation\n\nInstall the plugin with your package manager of choice (npm, yarn, pnpm).\n\n```sh\nnpm i -D eleventy-plugin-embed-cloudinary\n```\n\nAdd this plugin to your [Eleventy configuration file](https://www.11ty.dev/docs/config/) (usually `.eleventy.js`):\n\n```js\nconst embedCloudinary = require('eleventy-plugin-embed-cloudinary');\n\nmodule.exports = function(eleventyConfig) {\n  eleventyConfig.addPlugin(embedCloudinary, {\n    apiKey: 'YOUR_CLOUDINARY_API_KEY',\n    apiSecret: 'YOUR_CLOUDINARY_API_SECRET',\n    cloudName: 'YOUR_CLOUDINARY_CLOUD_NAME'\n  });\n};\n```\n\nYour 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.\n\n\u003e :warning: 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](https://docs.github.com/en/actions/reference/encrypted-secrets); if the build runs on Netlify, use [Build environment variables](https://docs.netlify.com/configure-builds/environment-variables/).\n\n## Configuration\n\n### Required parameters\n\n| Parameter | Explanation |\n| --- | --- |\n| `apiKey` | Your Cloudinary API key. |\n| `apiSecret` | Your Cloudinary API secret. |\n| `cloudName` | Your Cloudinary [cloud name]((https://cloudinary.com/documentation/how_to_integrate_cloudinary#create_and_tour_your_account)). |\n\n### Options\n\n| Option | Default | Explanation |\n| --- | --- | --- |\n| `cacheDirectory` | `.cache` | Directory where the 11ty `Cache` (see [eleventy-cache-assets](https://github.com/11ty/eleventy-cache-assets)) stores the responses from the Cloudinary API. It is strongly recommended that you add this folder to your `.gitignore` file. |\n| `cacheDuration` | `30m` | How long a response stored in the 11ty `Cache` should be considered valid. For the syntax, see [here](https://www.11ty.dev/docs/plugins/cache/#change-the-cache-duration). |\n| `classString` | `\"\"` | CSS class/es to apply to the generated `\u003cimg\u003e` element. |\n| `shouldLazyLoad` | `true` | Whether the generated `\u003cimg\u003e` element should have the attribute [loading=\"lazy\"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading) to instruct the browser to [defer loading the image](https://web.dev/browser-level-image-lazy-loading/) (browser support [here](https://caniuse.com/loading-lazy-attr)). |\n| `shouldThrowOnMissingAlt` | `false` | Whether this plugin should throw an error when fetching an image that does not have an `alt` attribute. See [here](https://support.cloudinary.com/hc/en-us/articles/202521142-Can-I-add-metadata-to-images-) how to add a Description (alt) to an image hosted on your Cloudinary Media Library. |\n| `shouldThrowOnMissingCaption` | `false` | Whether this plugin should throw an error when fetching an image that does not have a `caption` attribute. See [here](https://support.cloudinary.com/hc/en-us/articles/202521142-Can-I-add-metadata-to-images-) how to add a Title (caption) to an image hosted on your Cloudinary Media Library. |\n\n### Image version and image public ID\n\nFor each image URL you write in your markdown files, you will need to specify its [public ID](https://cloudinary.com/documentation/upload_images#public_id) (it's the last part of the URL, without the file extension) and its [version](https://cloudinary.com/documentation/upload_images#asset_versions).\n\n```markdown\nhttps://res.cloudinary.com/YOUR_CLOUDINARY_CLOUD_NAME/image/upload/YOUR_IMAGE_VERSION/YOUR_IMAGE_PUBLIC_ID.png\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackdbd%2Feleventy-plugin-embed-cloudinary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackdbd%2Feleventy-plugin-embed-cloudinary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackdbd%2Feleventy-plugin-embed-cloudinary/lists"}