Watermarking
Image Watermarking
Overlay your logo or badge on every image served through a CDN domain — applied at the edge, cached like any other variant, with no changes to your origin files.
How It Works
Watermarking is configured per domain and applied automatically — there are no URL parameters to add. When an image is fetched from your origin and processed at the edge, the watermark is composited onto it before the result is cached. Subsequent requests serve the watermarked image straight from cache.
- Upload a watermark image (PNG or WebP with transparency, up to 1 MB) in your domain's settings.
- Choose position, size, opacity, and margins.
- Every image served through the domain is watermarked from then on.
Watermarking requires image optimization to
be enabled on the domain — it runs as part of the same edge processing pipeline. The watermark asset is
stored in your Edge Storage account in a bucket named cdn-assets.
Settings
| Setting | Description | Default |
|---|---|---|
| Position | 9-point grid: corners, edges, or centre | bottom-right |
| Size | Watermark width as a percentage of the output image width (1–50%) | 15% |
| Opacity | 0–100% | 60% |
| Margin | Distance from the image edges in pixels | 16px |
| Minimum width | Images narrower than this are served without a watermark (thumbnails, placeholders) | 200px |
Behaviour Notes
Works with transforms
The watermark is applied after resizing and effects, so it scales correctly with
?width= and other
image optimization parameters.
Each transform variant is watermarked and cached independently. Animated GIFs are watermarked on every frame.
Cache updates are automatic
Changing the watermark image or its settings automatically applies to images as they are next requested — no purge required. Enabling watermarking on a busy domain causes a one-time re-cache of image variants.
Availability first
If the watermark asset is temporarily unavailable, images are served unwatermarked rather than failing — delivery is never blocked by watermarking.
Placeholders are excluded
LQIP placeholders and images below the minimum width are never watermarked — a logo on a 20px blur preview helps nobody.
Best Practices
-
Use a PNG or WebP with a transparent background — solid backgrounds look like a sticker. -
Upload at roughly 2x the largest size it will render (e.g. a 600px-wide logo file for a 15% overlay on 2000px images) so it stays crisp. -
60–70% opacity marks images clearly without ruining them; use 100% only for hard branding. -
Keep the minimum-width threshold at or above your thumbnail size so grids stay clean.