Document image transformation configuration

content/docs/configuration-options.md

@@ -102,6 +102,75 @@ 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` 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.
+
+`media_processing` accepts the following options. All options are optional unless marked required.
+
+* `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:
+  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.
+
+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.
+
+**Example:**
+
+```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
+```
+
+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.
+
+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
 
 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.

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 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**