Grammarly, fixed classification, addressed PR comments

Author: gzigzigzeo

docs/cache/external.mdx

@@ -12,10 +12,10 @@ Most major CDNs (Cloudflare, Fastly, AWS CloudFront, Akamai, etc.) can cache img
 
 ### Recommended CDN settings
 
-* **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin
 * **Image optimization** - Disable CDN image optimization to avoid double-processing
-* **Compression** - Enable gzip/Brotli compression for bandwidth savings
-* **HTTP/2 Server Push** - Push critical images to reduce latency
+* **Compression** - In case your CDN supports conditional compression of SVG images, enable gzip/Brotli compression for bandwidth savings
+* **Include essential headers*** - It's strongly recommended to include `Accept` header in the cache key. If you have client hints enabled, include also `DPR`, `Sec-CH-Dpr`, and `Sec-CH-Width` headers.
+* **Origin shield** - Add a secondary cache layer between your CDN and imgproxy origin if your CDN supports it.
 
 ## nginx caching
 
@@ -32,16 +32,24 @@ server {
   listen 80;
   server_name images.example.com;
 
-  # Include request and feature signals that can change imgproxy output
-  proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width";
+  # Uncomment if you do not use format negotiation and client hints
+  # proxy_cache_key "$scheme$proxy_host$request_uri";
+
+  # Uncomment if you use format negotiation
+  # proxy_cache_key "$scheme$proxy_host$request_uri$http_accept";
+
+  # Uncomment if you use client hints
+  # proxy_cache_key "$scheme$request_method$host$request_uri:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width";
+
+  # Uncomment if you use format negotiation and client hints
+  # proxy_cache_key "$scheme$request_method$host$request_uri:accept=$http_accept:dpr=$http_dpr:width=$http_width:chdpr=$http_sec_ch_dpr:chwidth=$http_sec_ch_width";
 
   location / {
     proxy_pass http://imgproxy;
 
     # Cache configuration
     proxy_cache imgproxy_cache;
-    proxy_cache_valid 200 24h;
-    proxy_cache_valid 304 24h;
+    proxy_cache_valid 200 30d;
     proxy_cache_valid 404 1m;
     proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
     proxy_cache_background_update on;
@@ -65,7 +73,7 @@ The exact key depends on which imgproxy features can change output for the same
 proxy_cache_key "$scheme$proxy_host$request_uri";
 ```
 
-2. Include format negotiation signal when WebP/AVIF/JXL preference can vary by client:
+2. Include [format negotiation](../configuration/options.mdx#avifwebpjpeg-xl-support-detection) signal when WebP/AVIF/JXL preference can vary by client:
 
 ```nginx
 proxy_cache_key "$scheme$proxy_host$request_uri$http_accept";
@@ -82,7 +90,7 @@ Use the smallest key that still prevents collisions for your traffic profile.
 ### Key recommendations
 
 * Include `Accept` in the cache key if format negotiation is used.
-* Include DPR/width-related hints in the cache key if Client Hints are used to vary output.
+* Include DPR/width-related hints in the cache key if [Client Hints](../configuration/options.mdx#client-hints-support) are used to vary output.
 * Set long `inactive` timeout (30d) to keep popular images in cache.
 * Configure `proxy_cache_use_stale` for graceful degradation during origin issues.
 * Monitor `/proc/sys/fs/file-max` and increase if needed for large caches.
@@ -163,10 +171,10 @@ sub vcl_hash {
 }
 
 sub vcl_backend_response {
-  # Cache successful responses for 24 hours
+  # Cache successful responses for 30 days
   if (beresp.status == 200) {
-    set beresp.ttl = 24h;
-    set beresp.keep = 24h;
+    set beresp.ttl = 30d;
+    set beresp.keep = 30d;
   }
 
   # Cache 404s for a short period

docs/cache/internal.mdx

@@ -66,14 +66,3 @@ When a request comes in:
 3. imgproxy checks if a cached image exists in the configured storage.
 4. If the cached image exists and is valid, imgproxy serves it directly.
 5. If not, imgproxy processes the image and stores the result in the cache before serving it.
-
-## Monitoring
-
-Monitor cache performance with metrics:
-
-* Cache hit rate
-* Cache size
-* Cache evictions
-* Cache latency
-
-These metrics are available through [monitoring endpoints](../monitoring/prometheus.mdx).

docs/cache/internal/amazon_s3.mdx

@@ -8,8 +8,8 @@ imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage.
 
 1. Set the `IMGPROXY_CACHE_USE` environment variable to `s3`.
 2. [Set up the necessary credentials](#set-up-credentials) to grant access to your cache bucket.
-3. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION`. Default: `us-west-1`
-4. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`.
+3. Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`.
+4. _(optional)_ Specify the AWS region with `IMGPROXY_CACHE_S3_REGION` or `AWS_REGION`. Default: `us-west-1`
 5. _(optional)_ Specify the S3 endpoint with `IMGPROXY_CACHE_S3_ENDPOINT`. You can also set `IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE=false` to use the virtual host style for the endpoint.
 6. _(optional)_ Specify the AWS IAM Role to Assume with `IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN`.
 7. _(optional)_ Specify the External ID to pass to the AWS IAM Role when assuming it using `IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID`. This will have no effect if the assume role ARN is not specified.

docs/cache/internal/azure_blob_storage.mdx

@@ -9,7 +9,7 @@ imgproxy can store cached images in Azure Blob Storage containers. To use Azure
 1. Set the `IMGPROXY_CACHE_USE` environment variable to `abs`.
 2. Set `IMGPROXY_CACHE_ABS_NAME` to your Azure account name.
 3. [Set up the necessary credentials](#set-up-credentials).
-4. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`.
+4. Specify the cache container name with `IMGPROXY_CACHE_BUCKET`.
 5. _(optional)_ Specify the Azure Blob Storage endpoint with `IMGPROXY_CACHE_ABS_ENDPOINT`.
 
 ### Configuration

docs/cache/internal/google_cloud_storage.mdx

@@ -8,7 +8,7 @@ imgproxy can store cached images in Google Cloud Storage buckets. To use the GCS
 
 1. Set the `IMGPROXY_CACHE_USE` environment variable to `gcs`.
 2. [Set up credentials](#setup-credentials) to grant access to your cache bucket.
-3. _(optional)_ Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`.
+3. Specify the cache bucket name with `IMGPROXY_CACHE_BUCKET`.
 4. _(optional)_ Specify the Google Cloud Storage endpoint with `IMGPROXY_CACHE_GCS_ENDPOINT`.
 
 ### Configuration

docs/cache/internal/local_filesystem.mdx

@@ -6,7 +6,7 @@ description: Learn about how to configure the local filesystem cache in imgproxy
 
 imgproxy can store cached images on the local filesystem. To use filesystem cache, do the following:
 
-1. Set the `IMGPROXY_CACHE_USE` environment variable to the filesystem.
+1. Set the `IMGPROXY_CACHE_USE` environment variable to `fs`.
 2. Set `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` to your cache directory path.
 3. _(optional)_ Specify a path prefix for cache files with `IMGPROXY_CACHE_PATH_PREFIX`.
 
@@ -25,5 +25,5 @@ imgproxy can store cached images on the local filesystem. To use filesystem cach
 Assume you want to cache processed images in `/var/cache/imgproxy`. Run imgproxy with `IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT` set to your cache directory:
 
 ```bash
-IMGPROXY_CACHE_USE=filesystem IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy
+IMGPROXY_CACHE_USE=fs IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT=/var/cache/imgproxy imgproxy
 ```

docs/cache/internal/openstack_swift.mdx

@@ -15,7 +15,7 @@ imgproxy can store cached images in OpenStack Object Storage, also known as Swif
    * `IMGPROXY_CACHE_SWIFT_TENANT`: the tenant name for cache (optional, v2 auth only). Default: blank
    * `IMGPROXY_CACHE_SWIFT_DOMAIN`: the Swift domain name for cache (optional, v3 auth only). Default: blank
 
-3. _(optional)_ Specify the cache container name with `IMGPROXY_CACHE_BUCKET`.
+3. Specify the cache container name with `IMGPROXY_CACHE_BUCKET`.
 
 ### Configuration
 

docs/configuration/options.mdx

@@ -48,9 +48,9 @@ echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
 * [`IMGPROXY_PATH_PREFIX`]: the URL path prefix. Example: when set to `/abc/def`, the imgproxy URL will be `/abc/def/%signature/%processing_options/%source_url`. Default: blank
 * [`IMGPROXY_USER_AGENT`]: the User-Agent header that will be sent with the source image request. You can use the `%current_version` variable to insert the current imgproxy version. Default: `imgproxy/%current_version`
 * [`IMGPROXY_USE_ETAG`]: when set to `true`, enables using the [ETag](https://en.wikipedia.org/wiki/HTTP_ETag) HTTP header for HTTP cache control. Default: `false`
-* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change it to invalidate old ETags and prevent `304 Not Modified` responses for stale client/CDN validators. Default: blank
+* [`IMGPROXY_ETAG_BUSTER`]: a global ETag buster value. Change this value if you update configuration that affects image processing, to invalidate old ETags and avoid `304 Not Modified` responses from stale client/CDN validators. Default: blank
 * [`IMGPROXY_USE_LAST_MODIFIED`]: when set to `true`, enables using the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) HTTP header for HTTP cache control. Default: `false`
-* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp. If incoming `If-Modified-Since` is older than this value, imgproxy ignores it and forces revalidation; if origin `Last-Modified` is older, imgproxy replaces it with this timestamp. Use it to invalidate stale client/CDN `Last-Modified` validators after global processing changes. Default: `0`
+* [`IMGPROXY_LAST_MODIFIED_BUSTER`]: a global `Last-Modified` buster timestamp in [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html) format. By setting it to a specific datetime, you can make imgproxy treat all the images as if they were modified at least at that datetime. Default: blank
 * [`IMGPROXY_CUSTOM_REQUEST_HEADERS`]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum`
 * [`IMGPROXY_CUSTOM_RESPONSE_HEADERS`]: ((pro)) a list of custom response headers, separated by `\;` (can be redefined by `IMGPROXY_CUSTOM_HEADERS_SEPARATOR`). Example: `X-MyHeader1=Lorem\;X-MyHeader2=Ipsum`
 * [`IMGPROXY_CUSTOM_HEADERS_SEPARATOR`]: ((pro)) a string that will be used as a custom header separator. Default: `\;`
@@ -167,8 +167,6 @@ When using imgproxy in a development environment, it can be useful to ignore SSL
 
 Also you may want imgproxy to respond with the same error message that it writes to the log:
 
-* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces.
-
 * [`IMGPROXY_ALLOW_SECURITY_OPTIONS`]: when `true`, allows usage of security-related processing options such as `max_src_resolution`, `max_src_file_size`, `max_animation_frames`, `max_animation_frame_resolution`, and `max_result_dimension`. Default: `false`.
 
   :::warning
@@ -423,24 +421,24 @@ imgproxy can detect objects on the image and use them to perform smart cropping,
 
 Read the [Object Detection guide](../features/object_detection.mdx) for more info.
 
-## Object classification
+## Classification
 
-imgproxy can classify detected objects on the image and provide detailed information about what the objects are.
+imgproxy can classify images by assigning them to predefined categories based on their overall content, similar to object detection but without identifying or locating individual objects.
 
-* [`IMGPROXY_OBJECT_CLASSIFY_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank
-* [`IMGPROXY_OBJECT_CLASSIFY_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank
-* [`IMGPROXY_OBJECT_CLASSIFY_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224
-* [`IMGPROXY_OBJECT_CLASSIFY_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5
-* [`IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are:
+* [`IMGPROXY_CLASSIFICATION_NET`]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank
+* [`IMGPROXY_CLASSIFICATION_CLASSES`]: ((pro)) the path to the text file with the class names, one per line. Default: blank
+* [`IMGPROXY_CLASSIFICATION_NET_SIZE`]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224
+* [`IMGPROXY_CLASSIFICATION_THRESHOLD`]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5
+* [`IMGPROXY_CLASSIFICATION_NORMALIZATION`]: ((pro)) the normalization type to apply to the input image. Possible values are:
   * `none`: _(default)_ no normalization
-  * `half`: normalize to [-0.5, 0.5] range
+  * `half`: normalize to [0, 1] range
   * `full`: normalize to [-1, 1] range
   * `imagenet`: normalize using ImageNet mean and standard deviation
-* [`IMGPROXY_OBJECT_CLASSIFY_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are:
-  * `nchw`: _(default)_ channels first
-  * `nhwc`: channels last
+* [`IMGPROXY_CLASSIFICATION_LAYOUT`]: ((pro)) the data layout of the neural network input. Possible values are:
+  * `nchw`: channels first (PyTorch default)
+  * `nhwc`: _(default)_ channels last (TensorFlow default)
 
-Read the [Object Classification guide](../features/object_classification.mdx) for more info.
+Read the [Classification guide](../features/classification.mdx) for more info.
 
 ## Cache
 
@@ -453,9 +451,11 @@ imgproxy can cache processed images in various storage backends to improve perfo
 * [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank
 * [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false`
 
+Read the [Internal cache guide](../cache/internal.mdx) for more info.
+
 ### Local filesystem {#cache-storage-local-filesystem}
 
-imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `filesystem`:
+imgproxy can store cached images on the local filesystem. To use [filesystem cache](../cache/internal/local_filesystem.mdx), set `IMGPROXY_CACHE_USE` to `fs`:
 
 * [`IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT`]: ((pro)) the root directory for filesystem cache. Default: blank
 
@@ -508,8 +508,6 @@ imgproxy can store cached images in OpenStack Object Storage (Swift). To use [Sw
 * [`IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS`]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60
 * [`IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS`]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10
 
-Read the [Internal cache guide](../cache/internal.mdx) for more info.
-
 ## Fallback image
 
 You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables: