From 981fc85f9146d348932120cd00abedcac0e2a8a3 Mon Sep 17 00:00:00 2001 From: Gretchen Shelby-Dormer Date: Tue, 5 Dec 2023 15:18:45 -0400 Subject: [PATCH 1/2] * Accept string or number for value of Inputs maxSize.height and maxSize.width so users can follow the instructions in https://cloudinary.com/blog/automatic_responsive_images_with_client_hints * Add Inputs maxSize.crop so users can specify a cloudinary crop mode for their images --- netlify-plugin-cloudinary/src/lib/cloudinary.ts | 2 +- netlify-plugin-cloudinary/src/types/integration.ts | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/netlify-plugin-cloudinary/src/lib/cloudinary.ts b/netlify-plugin-cloudinary/src/lib/cloudinary.ts index 4c7d25d..86abbf7 100644 --- a/netlify-plugin-cloudinary/src/lib/cloudinary.ts +++ b/netlify-plugin-cloudinary/src/lib/cloudinary.ts @@ -419,7 +419,7 @@ export function getTransformationsFromInputs(inputs: Inputs) { transformations.push({ height: maxSize.height, width: maxSize.width, - crop: 'limit', + crop: maxSize.crop || 'limit', dpr: maxSize.dpr }) } diff --git a/netlify-plugin-cloudinary/src/types/integration.ts b/netlify-plugin-cloudinary/src/types/integration.ts index e63419e..96525a5 100644 --- a/netlify-plugin-cloudinary/src/types/integration.ts +++ b/netlify-plugin-cloudinary/src/types/integration.ts @@ -10,9 +10,10 @@ export type Inputs = { imagesPath: string | Array; loadingStrategy: string; maxSize: { + crop: string; dpr: number | string; - height: number; - width: number; + height: number | string; + width: number | string; }; privateCdn: boolean; uploadPreset: string; From f8239aec2a880e6d708492c8239d9ada2b5dc452 Mon Sep 17 00:00:00 2001 From: Gretchen Shelby-Dormer Date: Tue, 5 Dec 2023 16:35:05 -0400 Subject: [PATCH 2/2] Update documentation * Include hyperlinks for new people --- README.md | 50 +++++++++++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index a4d71b7..688d41d 100644 --- a/README.md +++ b/README.md @@ -88,38 +88,50 @@ npm install netlify-plugin-cloudinary | Name | Type |Required | Example | Description | |-----------------|---------|---------|-----------| ------------| -| cloudName | string | No* | mycloud | Cloudinary Cloud Name | -| cname | string | No | domain.com | The custom domain name (CNAME) to use for building URLs (Advanced Plan Users) | -| deliveryType | string | No | fetch | The method by which Cloudinary stores and delivers images (Ex: fetch, upload) | +| [cloudName](#setting-your-cloud-name) | string | No* | mycloud | Cloudinary Cloud Name | +| cname | string | No | domain.com | [custom domain name (CNAME) to use for building URLs (Advanced Plan Users)](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames) | +| [deliveryType](#changing-your-delivery-type) | string | No | fetch | Cloudinary method for image storage and delivery (Ex: fetch, upload) | | folder | string | No | myfolder | Folder all media will be stored in. Defaults to Netlify site name | -| imagesPath | string/Array | No | /assets | Local path application serves image assets from | -| loadingStrategy | string | No | eager | The method in which in which images are loaded (Ex: lazy, eager) | -| maxSize | object | No | eager | See Below. | -| privateCdn | boolean | No | true | Enables Private CDN Distribution (Advanced Plan Users) | -| uploadPreset | string | No | my-preset | Defined set of asset upload defaults in Cloudinary | +| [imagesPath](#customizing-where-your-images-are-served-from) | string/Array | No | /assets | Local path application serves image assets from | +| loadingStrategy | string | No | eager | [`loading` attribute to use on images](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading) (Ex: lazy, eager) | +| [maxSize](#maxsize) | object | No | [plugins.inputs.maxSize]
crop = "limit"
dpr = "auto"
width = "auto:100:400"
height = 200 | Settings for optimizing Cloudinary image outputs | +| privateCdn | boolean | No | true | [Enables Private CDN Distribution (Advanced Plan Users)](https://cloudinary.com/documentation/advanced_url_delivery_options#private_cdns_and_cnames) | +| uploadPreset | string | No | my-preset | [Defined set of asset upload defaults in Cloudinary](https://cloudinary.com/documentation/upload_presets) | | uploadConcurrency | number | No | 10 | Maximum value of concurrent uploads | -*Cloud Name must be set as an environment variable if not as an input -#### Max Size +#### maxSize -The Max Size option gives you the ability to configure a maximum width and height that images will scale down to, helping to avoid serving unnecessarily large images. +`maxSize` gives you the ability to configure a maximum height and width that images will scale down to, helping to avoid serving unnecessarily large images. -By default, the aspect ratio of the images are preserved, so by specifying both a maximum width and height, you're telling Cloudinary to scale the image down so that neither the width or height are beyond that value. +By default, the aspect ratio of an image is preserved. -Additionally, the plugin uses a crop method of `limit` which avoids upscaling images if the images are already smaller than the given size, which reduces unnecessary upscaling as the browser will typically automatically handle. +By default, the Cloudinary crop mode `limit` is used to avoid upscaling an image if the image's original size is smaller than the maximum height and width; reduces unnecessary upscaling as the browser will typically automatically handle. The options available are: -| Name | Type | Example | Description | -|-----------------|---------|-----------| ------------| -| dpr | string | 2.0 | Device Pixel Ratio which essentially multiplies the width and height for pixel density. | -| height | number | 600 | Maximum height an image can be delivered as. | -| width | number | 800 | Maximum width an image can be delivered as. | +| Name | Type | Example | Description | +|-------------------|---------|-----------| ------------| +| `crop` | string | `"limit"` | [Cloudinary crop mode](https://cloudinary.com/documentation/resizing_and_cropping#resize_and_crop_modes) to apply to image. | +| `dpr` | string | `2.0` | [Device Pixel Ratio](https://cloudinary.com/documentation/resizing_and_cropping#set_device_pixel_ratio_dpr) which essentially multiplies the width and height for pixel density. | +| `height` | string or number | `"auto"` or `600` | Maximum [height](https://cloudinary.com/documentation/transformation_reference#h_height) an image can be delivered as. | +| `width` | string or number | `"auto:100:400"` or `800` | Maximum [width](https://cloudinary.com/documentation/transformation_reference#w_width) an image can be delivered as. | -It's important to note that this will not change the width or height attribute of the image within the DOM, this will only be the image that is being delivered by Cloudinary. +For users interested in [scaling images automatically with client hints](https://cloudinary.com/blog/automatic_responsive_images_with_client_hints), height and width accept string values like `"auto"` and `"auto:100:400"`. + +```toml + [plugins.inputs.maxSize] + crop = "limit" + dpr = "auto" + width = "auto:100:400" + height = 200 +``` + +It's important to note that these settings do **not** modify the width or height attributes of the image within the DOM; these settings **only** affect the image delivered by Cloudinary. ### Environment Variables +[Learn where to find these environment variable values.](https://www.youtube.com/watch?v=1SIp9VL5TMo) + | Name | Required | Example | Description | |------------------------|----------|----------|-------------| | CLOUDINARY_CLOUD_NAME | No* | mycloud | Cloudinary Cloud Name |