diff --git a/CHANGELOG.md b/CHANGELOG.md index b839f98c..22d72be2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,11 +16,11 @@ ### Added - AVIF support. - Azure Blob Storage support. -- `IMGPROXY_STRIP_COLOR_PROFILE` config and [strip_color_profile](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-color-profile) processing option. +- `IMGPROXY_STRIP_COLOR_PROFILE` config and [strip_color_profile](https://docs.imgproxy.net/#/generating_the_url?id=strip-color-profile) processing option. - `IMGPROXY_FORMAT_QUALITY` config. -- `IMGPROXY_AUTO_ROTATE` config and [auto_rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=auto-rotate) processing option. -- [rotate](https://docs.imgproxy.net/#/generating_the_url_advanced?id=rotate) processing option. -- `width` and `height` arguments of the [crop](https://docs.imgproxy.net/#/generating_the_url_advanced?id=crop) processing option can be less than `1` that is treated by imgproxy as a relative value (a.k.a. crop by percentage). +- `IMGPROXY_AUTO_ROTATE` config and [auto_rotate](https://docs.imgproxy.net/#/generating_the_url?id=auto-rotate) processing option. +- [rotate](https://docs.imgproxy.net/#/generating_the_url?id=rotate) processing option. +- `width` and `height` arguments of the [crop](https://docs.imgproxy.net/#/generating_the_url?id=crop) processing option can be less than `1` that is treated by imgproxy as a relative value (a.k.a. crop by percentage). - (pro) Remove Adobe Illustrator garbage from SVGs. - (pro) Add IPTC tags to the `/info` response. @@ -41,9 +41,9 @@ ### Added - Ability to skip processing of some formats. See [Skip processing](https://docs.imgproxy.net/#/configuration?id=skip-processing). - (pro) PDF support. -- (pro) [video_thumbnail_second](https://docs.imgproxy.net/#/generating_the_url_advanced?id=video-thumbnail-second) processing option. -- (pro) [page](https://docs.imgproxy.net/#/generating_the_url_advanced?id=page) processing option. -- (pro) [background_alpha](https://docs.imgproxy.net/#/generating_the_url_advanced?id=background-alpha) processing option. +- (pro) [video_thumbnail_second](https://docs.imgproxy.net/#/generating_the_url?id=video-thumbnail-second) processing option. +- (pro) [page](https://docs.imgproxy.net/#/generating_the_url?id=page) processing option. +- (pro) [background_alpha](https://docs.imgproxy.net/#/generating_the_url?id=background-alpha) processing option. - (pro) `IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE` and `IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION` configs. ### Changed @@ -61,8 +61,8 @@ ## [2.14.0] - 2020-07-17 ### Added - `IMGPROXY_PROMETHEUS_NAMESPACE` config. -- [strip_metadata](https://docs.imgproxy.net/#/generating_the_url_advanced?id=strip-metadata) processing option. -- (pro) Configurable unsharpening. See [Unsharpening](https://docs.imgproxy.net/#/configuration?id=unsharpening) configs and [unsharpening](https://docs.imgproxy.net/#/generating_the_url_advanced?id=unsharpening) processing option. +- [strip_metadata](https://docs.imgproxy.net/#/generating_the_url?id=strip-metadata) processing option. +- (pro) Configurable unsharpening. See [Unsharpening](https://docs.imgproxy.net/#/configuration?id=unsharpening) configs and [unsharpening](https://docs.imgproxy.net/#/generating_the_url?id=unsharpening) processing option. ### Changed - Better for libvips memory metrics for Prometheus. @@ -84,7 +84,7 @@ ## [2.13.0] - 2020-04-22 ### Added - Fallback images. -- [padding](https://docs.imgproxy.net/#/generating_the_url_advanced?id=padding) processing option. +- [padding](https://docs.imgproxy.net/#/generating_the_url?id=padding) processing option. ### Changed - Optimized memory usage. Especially when dealing with animated images. @@ -211,7 +211,7 @@ ## [2.4.0] - 2019-08-20 ### Added - `SO_REUSEPORT` socker option support. Can be enabled with `IMGPROXY_SO_REUSEPORT`. -- [filename](./docs/generating_the_url_advanced.md#filename) option. +- [filename](./docs/generating_the_url.md#filename) option. ### Changed - Better handling if non-sRGB images. @@ -228,8 +228,8 @@ - `libvips` v8.8 support: better processing of animated GIFs, built-in CMYK profile, better WebP scale-on-load, etc; - Animated WebP support. `IMGPROXY_MAX_GIF_FRAMES` is deprecated, use `IMGPROXY_MAX_ANIMATION_FRAMES`; - [HEIC support](./docs/image_formats_support.md#heic-support); -- [crop](./docs/generating_the_url_advanced.md#crop) processing option. `resizing_type:crop` is deprecated; -- Offsets for [gravity](./docs/generating_the_url_advanced.md#gravity); +- [crop](./docs/generating_the_url.md#crop) processing option. `resizing_type:crop` is deprecated; +- Offsets for [gravity](./docs/generating_the_url.md#gravity); - Resizing type `auto`. If both source and resulting dimensions have the same orientation (portrait or landscape), imgproxy will use `fill`. Otherwise, it will use `fit`; - Development errors mode. When `IMGPROXY_DEVELOPMENT_ERRORS_MODE` is true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack trace; - `IMGPROXY_KEEP_ALIVE_TIMEOUT` config. @@ -287,7 +287,7 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8. ## [2.2.5] - 2019-02-21 ### Added -- [extend](./docs/generating_the_url_advanced.md#extend) processing option. +- [extend](./docs/generating_the_url.md#extend) processing option. - `vips_memory_bytes`, `vips_max_memory_bytes` and `vips_allocs` metrics for Prometheus. ### Fixed @@ -357,15 +357,15 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8. ## [2.1.0] - 2018-11-16 ### Added -- [Plain source URLs](./docs/generating_the_url_advanced.md#plain) support. +- [Plain source URLs](./docs/generating_the_url.md#plain) support. - [Serving images from Google Cloud Storage](./docs/serving_files_from_google_cloud_storage.md). - [Full support of GIFs](./docs/image_formats_support.md#gif-support) including animated ones. - [Watermarks](./docs/watermark.md). - [New Relic](./docs/new_relic.md) metrics. - [Prometheus](./docs/prometheus.md) metrics. -- [DPR](./docs/generating_the_url_advanced.md#dpr) option (thanks to [selul](https://github.com/selul)). -- [Cache buster](./docs/generating_the_url_advanced.md#cache-buster) option. -- [Quality](./docs/generating_the_url_advanced.md#quality) option. +- [DPR](./docs/generating_the_url.md#dpr) option (thanks to [selul](https://github.com/selul)). +- [Cache buster](./docs/generating_the_url.md#cache-buster) option. +- [Quality](./docs/generating_the_url.md#quality) option. - Support for custom [Amazon S3](./docs/serving_files_from_s3.md) endpoints. - Support for [Amazon S3](./docs/serving_files_from_s3.md) versioning. - [Client hints](./docs/configuration.md#client-hints-support) support (thanks to [selul](https://github.com/selul)). @@ -394,13 +394,13 @@ Fixed processing of images with embedded profiles that was broken in v2.2.8. ## [2.0.0] - 2018-10-08 All-You-Ever-Wanted release! :tada: ### Added -- [New advanced URL format](./docs/generating_the_url_advanced.md). Unleash the full power of imgproxy v2.0. +- [New advanced URL format](./docs/generating_the_url.md). Unleash the full power of imgproxy v2.0. - [Presets](./docs/presets.md). Shorten your urls by reusing processing options. - [Serving images from Amazon S3](./docs/serving_files_from_s3.md). Thanks to [@crohr](https://github.com/crohr), now we have a way to serve files from private S3 buckets. - [Autoconverting to WebP when supported by browser](./docs/configuration.md#webp-support-detection) (disabled by default). Use WebP as resulting format when browser supports it. -- [Gaussian blur](./docs/generating_the_url_advanced.md#blur) and [sharpen](./docs/generating_the_url_advanced.md#sharpen) filters. Make your images look better than before. -- [Focus point gravity](./docs/generating_the_url_advanced.md#gravity). Tell imgproxy what point will be the center of the image. -- [Background color](./docs/generating_the_url_advanced.md#background). Control the color of background when converting PNG with alpha-channel to JPEG. +- [Gaussian blur](./docs/generating_the_url.md#blur) and [sharpen](./docs/generating_the_url.md#sharpen) filters. Make your images look better than before. +- [Focus point gravity](./docs/generating_the_url.md#gravity). Tell imgproxy what point will be the center of the image. +- [Background color](./docs/generating_the_url.md#background). Control the color of background when converting PNG with alpha-channel to JPEG. ### Changed - Key and salt are not required anymore. When key or salt is not specified, signature checking is disabled. diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 7f4d567d..2d5adbb8 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,8 +1,7 @@ * [Getting started](GETTING_STARTED) * [Installation](installation) * [Configuration](configuration) -* [Generating the URL (Basic)](generating_the_url_basic) -* [Generating the URL (Advanced)](generating_the_url_advanced) +* [Generating the URL](generating_the_url) * [Getting the image info pro](getting_the_image_info) * [Signing the URL](signing_the_url) * [Watermark](watermark) diff --git a/docs/generating_the_url_advanced.md b/docs/generating_the_url.md similarity index 90% rename from docs/generating_the_url_advanced.md rename to docs/generating_the_url.md index 6017ee7e..911324fb 100644 --- a/docs/generating_the_url_advanced.md +++ b/docs/generating_the_url.md @@ -1,10 +1,6 @@ -# Generating the URL (Advanced) +# Generating the URL -This guide describes the advanced URL format that allows the use of all the imgproxy features. Read our [Generating the URL (Basic)](generating_the_url_basic.md) guide to learn about the _basic_ URL format that is compatible with imgproxy 1.x. - -## Format definition - -The advanced URL should contain the signature, processing options, and source URL, like this: +The URL should contain the signature, processing options, and source URL, like this: ``` /%signature/%processing_options/plain/%source_url@%extension @@ -13,13 +9,13 @@ The advanced URL should contain the signature, processing options, and source UR Check out the [example](#example) at the end of this guide. -### Signature +## Signature Signature protects your URL from being altered by an attacker. It is highly recommended to sign imgproxy URLs in production. Once you set up your [URL signature](configuration.md#url-signature), check out the [Signing the URL](signing_the_url.md) guide to know how to sign your URLs. Otherwise, use any string here. -### Processing options +## Processing options Processing options should be specified as URL parts divided by slashes (`/`). Processing option has the following format: @@ -31,7 +27,7 @@ The list of processing options does not define imgproxy's processing pipeline. I imgproxy supports the following processing options: -#### Resize +### Resize ``` resize:%resizing_type:%width:%height:%enlarge:%extend @@ -40,7 +36,7 @@ rs:%resizing_type:%width:%height:%enlarge:%extend Meta-option that defines the [resizing type](#resizing-type), [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values. -#### Size +### Size ``` size:%width:%height:%enlarge:%extend @@ -49,7 +45,7 @@ s:%width:%height:%enlarge:%extend Meta-option that defines the [width](#width), [height](#height), [enlarge](#enlarge), and [extend](#extend). All arguments are optional and can be omitted to use their default values. -#### Resizing type +### Resizing type ``` resizing_type:%resizing_type @@ -64,7 +60,7 @@ Defines how imgproxy will resize the source image. Supported resizing types are: Default: `fit` -#### Resizing algorithmpro +### Resizing algorithmpro ``` resizing_algorithm:%algorithm @@ -75,7 +71,7 @@ Defines the algorithm that imgproxy will use for resizing. Supported algorithms Default: `lanczos3` -#### Width +### Width ``` width:%width @@ -86,7 +82,7 @@ Defines the width of the resulting image. When set to `0`, imgproxy will calcula Default: `0` -#### Height +### Height ``` height:%height @@ -97,7 +93,7 @@ Defines the height of the resulting image. When set to `0`, imgproxy will calcul Default: `0` -#### Dpr +### Dpr ``` dpr:%dpr @@ -107,7 +103,7 @@ When set, imgproxy will multiply the image dimensions according to this factor f Default: `1` -#### Enlarge +### Enlarge ``` enlarge:%enlarge @@ -118,7 +114,7 @@ When set to `1`, `t` or `true`, imgproxy will enlarge the image if it is smaller Default: false -#### Extend +### Extend ``` extend:%extend:%gravity @@ -130,7 +126,7 @@ ex:%extend:%gravity Default: `false:ce:0:0` -#### Gravity +### Gravity ``` gravity:%type:%x_offset:%y_offset @@ -158,7 +154,7 @@ Default: `ce:0:0` * `gravity:sm` - smart gravity. `libvips` detects the most "interesting" section of the image and considers it as the center of the resulting image. Offsets are not applicable here; * `gravity:fp:%x:%y` - focus point gravity. `x` and `y` are floating point numbers between 0 and 1 that define the coordinates of the center of the resulting image. Treat 0 and 1 as right/left for `x` and top/bottom for `y`. -#### Crop +### Crop ``` crop:%width:%height:%gravity @@ -173,7 +169,7 @@ Defines an area of the image to be processed (crop before resize). * When `width` or `height` is set to `0`, imgproxy will use the full width/height of the source image. * `gravity` _(optional)_ accepts the same values as [gravity](#gravity) option. When `gravity` is not set, imgproxy will use the value of the [gravity](#gravity) option. -#### Padding +### Padding ``` padding:%top:%right:%bottom:%left @@ -191,7 +187,7 @@ Defines padding size in css manner. All arguments are optional but at least one **📝Note:** Padding follows [dpr](#dpr) option so it will be scaled too if you set it. -#### Trim +### Trim ``` trim:%threshold:%color:%equal_hor:%equal_ver @@ -211,7 +207,7 @@ Removes surrounding background. **📝Note:** Trimming of animated images is not supported. -#### Rotate +### Rotate ``` rotate:%angle @@ -224,7 +220,7 @@ Rotates the image on the specified angle. The orientation from the image metadat Default: 0. -#### Quality +### Quality ``` quality:%quality @@ -235,7 +231,7 @@ Redefines quality of the resulting image, percentage. When `0`, quality is assum Default: 0. -#### Max Bytes +### Max Bytes ``` max_bytes:%bytes @@ -250,7 +246,7 @@ When set, imgproxy automatically degrades the quality of the image until the ima Default: 0 -#### Background +### Background ``` background:%R:%G:%B @@ -266,7 +262,7 @@ With no arguments provided, disables any background manipulations. Default: disabled -#### Background alphapro +### Background alphapro ``` background_alpha:%alpha @@ -277,7 +273,7 @@ Adds alpha channel to `background`. `alpha` is a positive floating point number Default: 1 -#### Adjustpro +### Adjustpro ``` adjust:%brightness:%contrast:%saturation @@ -286,7 +282,7 @@ a:%brightness:%contrast:%saturation Meta-option that defines the [brightness](#brightness), [contrast](#contrast), and [saturation](#saturation). All arguments are optional and can be omitted to use their default values. -#### Brightnesspro +### Brightnesspro ``` brightness:%brightness @@ -297,7 +293,7 @@ When set, imgproxy will adjust brightness of the resulting image. `brightness` i Default: 0 -#### Contrastpro +### Contrastpro ``` contrast:%contrast @@ -308,7 +304,7 @@ When set, imgproxy will adjust contrast of the resulting image. `contrast` is a Default: 1 -#### Saturationpro +### Saturationpro ``` saturation:%saturation @@ -319,7 +315,7 @@ When set, imgproxy will adjust saturation of the resulting image. `saturation` i Default: 1 -#### Blur +### Blur ``` blur:%sigma @@ -330,7 +326,7 @@ When set, imgproxy will apply the gaussian blur filter to the resulting image. ` Default: disabled -#### Sharpen +### Sharpen ``` sharpen:%sigma @@ -343,7 +339,7 @@ As an approximate guideline, use 0.5 sigma for 4 pixels/mm (display resolution), Default: disabled -#### Pixelatepro +### Pixelatepro ``` pixelate:%size @@ -354,7 +350,7 @@ When set, imgproxy will apply the pixelate filter to the resulting image. `size` Default: disabled -#### Unsharpeningpro +### Unsharpeningpro ``` unsharpening:%mode:%weight:%dividor @@ -363,7 +359,7 @@ ush:%mode:%weight:%dividor Allows redefining unsharpening options. All arguments have the same meaning as [Unsharpening](configuration.md#unsharpening) configs. All arguments are optional and can be omitted. -#### Watermark +### Watermark ``` watermark:%opacity:%position:%x_offset:%y_offset:%scale @@ -389,7 +385,7 @@ Puts watermark on the processed image. Default: disabled -#### Watermark URLpro +### Watermark URLpro ``` watermark_url:%url @@ -400,7 +396,7 @@ When set, imgproxy will use the image from the specified URL as a watermark. `ur Default: blank -#### Stylepro +### Stylepro ``` style:%style @@ -411,7 +407,7 @@ When set, imgproxy will prepend `