From 39f4d507d8181e999ef08ee81f9412c7350992ee Mon Sep 17 00:00:00 2001 From: Evan Frenkel Date: Mon, 22 Jun 2026 11:54:46 -0700 Subject: [PATCH 1/3] docs: add image transformation configuration --- content/docs/configuration-options.md | 19 +++++++ content/docs/image-transformations.md | 80 +++++++++++++++++++++++++++ content/docs/widgets/image.md | 20 +++++++ 3 files changed, 119 insertions(+) create mode 100644 content/docs/image-transformations.md diff --git a/content/docs/configuration-options.md b/content/docs/configuration-options.md index df9e2fe1..e5f3849b 100644 --- a/content/docs/configuration-options.md +++ b/content/docs/configuration-options.md @@ -102,6 +102,25 @@ Based on the settings above, if a user used an image widget field called `avatar This setting can be set to an absolute URL e.g. `https://netlify.com/media` should you wish, however in general this is not advisable as content should have relative paths to other content. +### Media Processing + +The `media_processing` option transforms supported image uploads before they are saved. It can convert images to JPEG or WebP, adjust quality, strip metadata, resize images, and crop uploads to an aspect ratio. + +```yaml +media_processing: + enabled: true + format: + enabled: true + default: webp + quality: 80 + strip_metadata: true + width: 1600 + height: null + aspect_ratio: 16x9 +``` + +You can set this globally or on an individual field. See [Image Transformations](/docs/image-transformations/) for the full option reference. + ## Media Library Media library integrations are configured via the `media_library` property, and its value should be an object with at least a `name` property. A `config` property can also be used for options that should be passed to the library in use. diff --git a/content/docs/image-transformations.md b/content/docs/image-transformations.md new file mode 100644 index 00000000..6b6b3bd6 --- /dev/null +++ b/content/docs/image-transformations.md @@ -0,0 +1,80 @@ +--- +title: Image Transformations +group: Media +weight: 5 +--- + +Decap CMS can transform image uploads in the browser before saving them through your configured backend or asset store integration. Use image transformations to normalize uploaded image formats, compression, dimensions, aspect ratios, and metadata before the file is committed or uploaded. + +Image transformations apply to JPEG, PNG, and WebP files uploaded directly through Decap CMS. Unsupported image types, such as GIF and SVG, are uploaded unchanged. + +## Global configuration + +Add `media_processing` at the top level of your `config.yml` file to apply the same processing settings to all direct image uploads. + +```yaml +media_processing: + enabled: true + format: + enabled: true + default: webp + quality: 80 + strip_metadata: true + width: 1600 + height: null + aspect_ratio: 16x9 +``` + +The example above saves supported uploads as WebP, compresses them at 80% quality, strips metadata, center-crops them to 16:9, and resizes them to 1600 x 900. + +## Field configuration + +You can also add `media_processing` to a field. Field-level processing is useful when a specific image field needs a different size or format than the rest of the site. + +```yaml +collections: + - name: posts + label: Posts + folder: content/posts + fields: + - label: Featured Image + name: image + widget: image + media_processing: + enabled: true + format: + enabled: true + default: jpeg + quality: 85 + width: 1200 + height: null + aspect_ratio: 3x2 +``` + +When `media_processing` is set on a field, that field uses its own processing configuration instead of the top-level `media_processing` configuration. + +## Options + +* `enabled` (*required*): enables or disables image processing. +* `format`: converts supported uploads to another output format. + * `enabled`: enables or disables format conversion. + * `default`: output format. Accepted values are `jpeg` and `webp`. +* `quality`: output quality from `1` to `100`. This is most useful for JPEG and WebP output. +* `strip_metadata`: when `true`, removes image metadata by re-encoding the uploaded image. +* `width`: output width in pixels. Set to `null` or omit it to avoid forcing a width. +* `height`: output height in pixels. Set to `null` or omit it to avoid forcing a height. +* `aspect_ratio`: optional crop ratio. Accepted values are positive numbers or ratio strings such as `16x9`, `16:9`, or `16_9`. + +## Dimensions and aspect ratios + +If you provide `width` without `height`, Decap CMS calculates the height from `aspect_ratio` or from the original image ratio. If you provide `height` without `width`, Decap CMS calculates the width the same way. + +If you provide both `width` and `height`, Decap CMS outputs those exact dimensions. If you also provide `aspect_ratio`, the source image is center-cropped to that ratio before resizing. + +If you provide `aspect_ratio` without dimensions, Decap CMS center-crops the source image to that ratio and keeps the cropped source size. + +## Output file names + +When format conversion is enabled, Decap CMS updates the uploaded file extension to match the output format. For example, `hero.png` becomes `hero.webp` when `format.default` is `webp`, and `hero.png` becomes `hero.jpg` when `format.default` is `jpeg`. + +When format conversion is disabled or omitted, the output file keeps the original supported image format. diff --git a/content/docs/widgets/image.md b/content/docs/widgets/image.md index 04e07bd7..d8846da2 100644 --- a/content/docs/widgets/image.md +++ b/content/docs/widgets/image.md @@ -21,6 +21,7 @@ The image widget allows editors to upload an image or select an existing one fro - `config`: a configuration object passed directly to the media library; check the documentation of your media library extension for available `config` options - `media_folder` (Beta): file path where uploaded images will be saved specific to this control. Paths can be relative to a collection folder (e.g. `images` will add the image to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with `/` (e.g `/static/images` will save uploaded images to the `static` folder in a sub folder named `images`) - `public_folder` *(defaults to the value of `media_folder`, with an opening `/` if one is not already included.)*: specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site. The value of the field is generated by prepending this path to the filename of the selected file. +- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the global `media_processing` configuration. See [Image Transformations](/docs/image-transformations/) for available options. - `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden **Example** @@ -36,6 +37,25 @@ The image widget allows editors to upload an image or select an existing one fro multiple: true ``` +### Image Transformation Overrides + +You can use `media_processing` on an image field when a specific field needs its own output format, dimensions, quality, or aspect ratio. + +```yaml +- label: "Featured Image" + name: "thumbnail" + widget: "image" + media_processing: + enabled: true + format: + enabled: true + default: webp + quality: 80 + width: 1600 + height: null + aspect_ratio: 16x9 +``` + ### Image Size Limit You can set a limit on the maximum file size that users can upload directly into an image field. From a1eb755e8aa978227cf3004663d58625db039c97 Mon Sep 17 00:00:00 2001 From: Evan Frenkel Date: Mon, 22 Jun 2026 12:10:57 -0700 Subject: [PATCH 2/3] docs: move image transformations into configuration options --- content/docs/configuration-options.md | 62 ++++++++++++++++++++- content/docs/image-transformations.md | 80 --------------------------- content/docs/widgets/image.md | 2 +- 3 files changed, 61 insertions(+), 83 deletions(-) delete mode 100644 content/docs/image-transformations.md diff --git a/content/docs/configuration-options.md b/content/docs/configuration-options.md index e5f3849b..9ae65322 100644 --- a/content/docs/configuration-options.md +++ b/content/docs/configuration-options.md @@ -104,7 +104,13 @@ This setting can be set to an absolute URL e.g. `https://netlify.com/media` shou ### Media Processing -The `media_processing` option transforms supported image uploads before they are saved. It can convert images to JPEG or WebP, adjust quality, strip metadata, resize images, and crop uploads to an aspect ratio. +Decap CMS can transform image uploads in the browser before saving them through your configured backend or asset store integration. Use image transformations to normalize uploaded image formats, compression, dimensions, aspect ratios, and metadata before the file is committed or uploaded. + +Image transformations apply to JPEG, PNG, and WebP files uploaded directly through Decap CMS. Unsupported image types, such as GIF and SVG, are uploaded unchanged. + +#### Global configuration + +Add `media_processing` at the top level of your `config.yml` file to apply the same processing settings to all direct image uploads. ```yaml media_processing: @@ -119,7 +125,59 @@ media_processing: aspect_ratio: 16x9 ``` -You can set this globally or on an individual field. See [Image Transformations](/docs/image-transformations/) for the full option reference. +The example above saves supported uploads as WebP, compresses them at 80% quality, strips metadata, center-crops them to 16:9, and resizes them to 1600 x 900. + +#### Field configuration + +You can also add `media_processing` to a field. Field-level processing is useful when a specific image field needs a different size or format than the rest of the site. + +```yaml +collections: + - name: posts + label: Posts + folder: content/posts + fields: + - label: Featured Image + name: image + widget: image + media_processing: + enabled: true + format: + enabled: true + default: jpeg + quality: 85 + width: 1200 + height: null + aspect_ratio: 3x2 +``` + +When `media_processing` is set on a field, that field uses its own processing configuration instead of the top-level `media_processing` configuration. + +#### Options + +* `enabled` (*required*): enables or disables image processing. +* `format`: converts supported uploads to another output format. + * `enabled`: enables or disables format conversion. + * `default`: output format. Accepted values are `jpeg` and `webp`. +* `quality`: output quality from `1` to `100`. This is most useful for JPEG and WebP output. +* `strip_metadata`: when `true`, removes image metadata by re-encoding the uploaded image. +* `width`: output width in pixels. Set to `null` or omit it to avoid forcing a width. +* `height`: output height in pixels. Set to `null` or omit it to avoid forcing a height. +* `aspect_ratio`: optional crop ratio. Accepted values are positive numbers or ratio strings such as `16x9`, `16:9`, or `16_9`. + +#### Dimensions and aspect ratios + +If you provide `width` without `height`, Decap CMS calculates the height from `aspect_ratio` or from the original image ratio. If you provide `height` without `width`, Decap CMS calculates the width the same way. + +If you provide both `width` and `height`, Decap CMS outputs those exact dimensions. If you also provide `aspect_ratio`, the source image is center-cropped to that ratio before resizing. + +If you provide `aspect_ratio` without dimensions, Decap CMS center-crops the source image to that ratio and keeps the cropped source size. + +#### Output file names + +When format conversion is enabled, Decap CMS updates the uploaded file extension to match the output format. For example, `hero.png` becomes `hero.webp` when `format.default` is `webp`, and `hero.png` becomes `hero.jpg` when `format.default` is `jpeg`. + +When format conversion is disabled or omitted, the output file keeps the original supported image format. ## Media Library diff --git a/content/docs/image-transformations.md b/content/docs/image-transformations.md deleted file mode 100644 index 6b6b3bd6..00000000 --- a/content/docs/image-transformations.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Image Transformations -group: Media -weight: 5 ---- - -Decap CMS can transform image uploads in the browser before saving them through your configured backend or asset store integration. Use image transformations to normalize uploaded image formats, compression, dimensions, aspect ratios, and metadata before the file is committed or uploaded. - -Image transformations apply to JPEG, PNG, and WebP files uploaded directly through Decap CMS. Unsupported image types, such as GIF and SVG, are uploaded unchanged. - -## Global configuration - -Add `media_processing` at the top level of your `config.yml` file to apply the same processing settings to all direct image uploads. - -```yaml -media_processing: - enabled: true - format: - enabled: true - default: webp - quality: 80 - strip_metadata: true - width: 1600 - height: null - aspect_ratio: 16x9 -``` - -The example above saves supported uploads as WebP, compresses them at 80% quality, strips metadata, center-crops them to 16:9, and resizes them to 1600 x 900. - -## Field configuration - -You can also add `media_processing` to a field. Field-level processing is useful when a specific image field needs a different size or format than the rest of the site. - -```yaml -collections: - - name: posts - label: Posts - folder: content/posts - fields: - - label: Featured Image - name: image - widget: image - media_processing: - enabled: true - format: - enabled: true - default: jpeg - quality: 85 - width: 1200 - height: null - aspect_ratio: 3x2 -``` - -When `media_processing` is set on a field, that field uses its own processing configuration instead of the top-level `media_processing` configuration. - -## Options - -* `enabled` (*required*): enables or disables image processing. -* `format`: converts supported uploads to another output format. - * `enabled`: enables or disables format conversion. - * `default`: output format. Accepted values are `jpeg` and `webp`. -* `quality`: output quality from `1` to `100`. This is most useful for JPEG and WebP output. -* `strip_metadata`: when `true`, removes image metadata by re-encoding the uploaded image. -* `width`: output width in pixels. Set to `null` or omit it to avoid forcing a width. -* `height`: output height in pixels. Set to `null` or omit it to avoid forcing a height. -* `aspect_ratio`: optional crop ratio. Accepted values are positive numbers or ratio strings such as `16x9`, `16:9`, or `16_9`. - -## Dimensions and aspect ratios - -If you provide `width` without `height`, Decap CMS calculates the height from `aspect_ratio` or from the original image ratio. If you provide `height` without `width`, Decap CMS calculates the width the same way. - -If you provide both `width` and `height`, Decap CMS outputs those exact dimensions. If you also provide `aspect_ratio`, the source image is center-cropped to that ratio before resizing. - -If you provide `aspect_ratio` without dimensions, Decap CMS center-crops the source image to that ratio and keeps the cropped source size. - -## Output file names - -When format conversion is enabled, Decap CMS updates the uploaded file extension to match the output format. For example, `hero.png` becomes `hero.webp` when `format.default` is `webp`, and `hero.png` becomes `hero.jpg` when `format.default` is `jpeg`. - -When format conversion is disabled or omitted, the output file keeps the original supported image format. diff --git a/content/docs/widgets/image.md b/content/docs/widgets/image.md index d8846da2..82203427 100644 --- a/content/docs/widgets/image.md +++ b/content/docs/widgets/image.md @@ -21,7 +21,7 @@ The image widget allows editors to upload an image or select an existing one fro - `config`: a configuration object passed directly to the media library; check the documentation of your media library extension for available `config` options - `media_folder` (Beta): file path where uploaded images will be saved specific to this control. Paths can be relative to a collection folder (e.g. `images` will add the image to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with `/` (e.g `/static/images` will save uploaded images to the `static` folder in a sub folder named `images`) - `public_folder` *(defaults to the value of `media_folder`, with an opening `/` if one is not already included.)*: specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site. The value of the field is generated by prepending this path to the filename of the selected file. -- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the global `media_processing` configuration. See [Image Transformations](/docs/image-transformations/) for available options. +- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the global `media_processing` configuration. See [Media Processing](/docs/configuration-options/#media-processing) for available options. - `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden **Example** From 581900d9d9c7bf3c32e8b760d051ddca593ddfd0 Mon Sep 17 00:00:00 2001 From: Yan <61414485+yanthomasdev@users.noreply.github.com> Date: Mon, 22 Jun 2026 18:00:40 -0300 Subject: [PATCH 3/3] Rework to fit with other sections --- content/docs/configuration-options.md | 40 +++++++++++---------------- content/docs/widgets/image.md | 21 +------------- 2 files changed, 17 insertions(+), 44 deletions(-) diff --git a/content/docs/configuration-options.md b/content/docs/configuration-options.md index 9ae65322..6dd0597e 100644 --- a/content/docs/configuration-options.md +++ b/content/docs/configuration-options.md @@ -102,15 +102,25 @@ Based on the settings above, if a user used an image widget field called `avatar This setting can be set to an absolute URL e.g. `https://netlify.com/media` should you wish, however in general this is not advisable as content should have relative paths to other content. -### Media Processing +## Media Processing -Decap CMS can transform image uploads in the browser before saving them through your configured backend or asset store integration. Use image transformations to normalize uploaded image formats, compression, dimensions, aspect ratios, and metadata before the file is committed or uploaded. +The `media_processing` setting controls image transformations that run in the browser before Decap CMS saves uploads through the configured backend or asset store integration. Image transformations apply to JPEG, PNG, and WebP files uploaded directly through Decap CMS. Unsupported image types, such as GIF and SVG, are uploaded unchanged. -#### Global configuration +`media_processing` accepts the following options. All options are optional unless marked required. -Add `media_processing` at the top level of your `config.yml` file to apply the same processing settings to all direct image uploads. +* `enabled` (required): enables or disables image processing. +* `format`: converts supported uploads to another output format. + * `enabled`: enables or disables format conversion. + * `default`: output format. Accepted values are `jpeg` and `webp`. +* `quality`: output quality from `1` to `100`. This is most useful for JPEG and WebP output. +* `strip_metadata`: when set to `true`, removes image metadata by re-encoding the uploaded image. +* `width`: output width in pixels. Set to `null` or omit it to avoid forcing a width. +* `height`: output height in pixels. Set to `null` or omit it to avoid forcing a height. +* `aspect_ratio`: optional crop ratio. Accepted values are positive numbers or ratio strings such as `16x9`, `16:9`, or `16_9`. + +**Example:** ```yaml media_processing: @@ -127,9 +137,9 @@ media_processing: The example above saves supported uploads as WebP, compresses them at 80% quality, strips metadata, center-crops them to 16:9, and resizes them to 1600 x 900. -#### Field configuration +You can also add `media_processing` to an image field. Field-level processing overrides the top-level `media_processing` configuration and is useful when a specific image field needs a different output format, dimensions, quality, or aspect ratio. -You can also add `media_processing` to a field. Field-level processing is useful when a specific image field needs a different size or format than the rest of the site. +**Example:** ```yaml collections: @@ -151,30 +161,12 @@ collections: aspect_ratio: 3x2 ``` -When `media_processing` is set on a field, that field uses its own processing configuration instead of the top-level `media_processing` configuration. - -#### Options - -* `enabled` (*required*): enables or disables image processing. -* `format`: converts supported uploads to another output format. - * `enabled`: enables or disables format conversion. - * `default`: output format. Accepted values are `jpeg` and `webp`. -* `quality`: output quality from `1` to `100`. This is most useful for JPEG and WebP output. -* `strip_metadata`: when `true`, removes image metadata by re-encoding the uploaded image. -* `width`: output width in pixels. Set to `null` or omit it to avoid forcing a width. -* `height`: output height in pixels. Set to `null` or omit it to avoid forcing a height. -* `aspect_ratio`: optional crop ratio. Accepted values are positive numbers or ratio strings such as `16x9`, `16:9`, or `16_9`. - -#### Dimensions and aspect ratios - If you provide `width` without `height`, Decap CMS calculates the height from `aspect_ratio` or from the original image ratio. If you provide `height` without `width`, Decap CMS calculates the width the same way. If you provide both `width` and `height`, Decap CMS outputs those exact dimensions. If you also provide `aspect_ratio`, the source image is center-cropped to that ratio before resizing. If you provide `aspect_ratio` without dimensions, Decap CMS center-crops the source image to that ratio and keeps the cropped source size. -#### Output file names - When format conversion is enabled, Decap CMS updates the uploaded file extension to match the output format. For example, `hero.png` becomes `hero.webp` when `format.default` is `webp`, and `hero.png` becomes `hero.jpg` when `format.default` is `jpeg`. When format conversion is disabled or omitted, the output file keeps the original supported image format. diff --git a/content/docs/widgets/image.md b/content/docs/widgets/image.md index 82203427..b19f382a 100644 --- a/content/docs/widgets/image.md +++ b/content/docs/widgets/image.md @@ -21,7 +21,7 @@ The image widget allows editors to upload an image or select an existing one fro - `config`: a configuration object passed directly to the media library; check the documentation of your media library extension for available `config` options - `media_folder` (Beta): file path where uploaded images will be saved specific to this control. Paths can be relative to a collection folder (e.g. `images` will add the image to a sub-folder in the collection folder) or absolute with reference to the base of the repo which needs to begin with `/` (e.g `/static/images` will save uploaded images to the `static` folder in a sub folder named `images`) - `public_folder` *(defaults to the value of `media_folder`, with an opening `/` if one is not already included.)*: specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site. The value of the field is generated by prepending this path to the filename of the selected file. -- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the global `media_processing` configuration. See [Media Processing](/docs/configuration-options/#media-processing) for available options. +- `media_processing`: image transformation settings to apply to uploads from this field. Field-level settings override the top-level `media_processing` configuration. See [Media Processing](/docs/configuration-options/#media-processing) for available options. - `choose_url`: *(default: `true`)* when set to `false`, the "Insert from URL" button will be hidden **Example** @@ -37,25 +37,6 @@ The image widget allows editors to upload an image or select an existing one fro multiple: true ``` -### Image Transformation Overrides - -You can use `media_processing` on an image field when a specific field needs its own output format, dimensions, quality, or aspect ratio. - -```yaml -- label: "Featured Image" - name: "thumbnail" - widget: "image" - media_processing: - enabled: true - format: - enabled: true - default: webp - quality: 80 - width: 1600 - height: null - aspect_ratio: 16x9 -``` - ### Image Size Limit You can set a limit on the maximum file size that users can upload directly into an image field.