README.md in imgix-4.0.3 vs README.md in imgix-4.1.0
- old
+ new
@@ -1,12 +1,12 @@
<!-- ix-docs-ignore -->
-`imgix-rb` is a client library for generating image URLs with [imgix](https://www.imgix.com/). It is tested under Ruby versions `2.3.0`, `2.2.4`, `2.1.8`, `jruby-9.2.11.0`, and `rbx-3.107`.
+`imgix-rb` is a client library for generating image URLs with [imgix](https://www.imgix.com/). It is tested under Ruby versions `3.1`, `3.0`, `2.7`, and `jruby-9.2.11.0`.
[](https://rubygems.org/gems/imgix)
-[](https://travis-ci.com/imgix/imgix-rb)
+[](https://circleci.com/gh/imgix/imgix-rb)
[](https://github.com/imgix/imgix-rb/blob/main/LICENSE)
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fimgix%2Fimgix-rb?ref=badge_shield)
---
@@ -54,16 +54,25 @@
client.path('/images/demo.png').to_url(w: 200)
#=> https://your-subdomain.imgix.net/images/demo.png?w=200&s=2eadddacaa9bba4b88900d245f03f51e
```
+To disable path encoding, pass `{disable_path_encoding: true}` as the second argument to the `Imgix#Path#to_url` function.
+
+```rb
+client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token')
+client.path('/[images]/demo.png').to_url
+#=> https://your-subdomain.imgix.net/%5Bimages%5D/demo.png?s=270832685733a36ba02bd8ab9fd72df5
+client.path('/[images]/demo.png').to_url({},{disable_path_encoding: true})
+#=> https://your-subdomain.imgix.net/[images]/demo.png?s=ed6eb07e9eff3f6c8bbcc83fc4f63198
+```
## Srcset Generation
The imgix gem allows for generation of custom `srcset` attributes, which can be invoked through `Imgix::Path#to_srcset`. By default, the `srcset` generated will allow for responsive size switching by building a list of image-width mappings.
```rb
-client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token', include_library_param: false)
+client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token')
path = client.path('/images/demo.png')
srcset = path.to_srcset
```
@@ -81,11 +90,11 @@
### Fixed image rendering
In cases where enough information is provided about an image's dimensions, `to_srcset` will instead build a `srcset` that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are `w` or `h`. By invoking `to_srcset` with either a width **or** height provided, a different `srcset` will be generated for a fixed-size image instead.
```rb
-client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token', include_library_param: false)
+client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token')
path = client.path('/images/demo.png')
srcset = path.to_srcset(h:800, ar:'3:2', fit:'crop')
```
@@ -104,11 +113,11 @@
### Custom Widths
In situations where specific widths are desired when generating `srcset` pairs, a user can specify them by passing an array of integers via `widths` to the `options` keyword argument.
```rb
-@client ||= Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
+@client ||= Imgix::Client.new(domain: 'testing.imgix.net')
.path('image.jpg')
.to_srcset(options: { widths: [100, 500, 1000, 1800] })
```
Will generate the following `srcset` of width pairs:
@@ -127,11 +136,11 @@
The `srcset` width tolerance dictates the maximum tolerated size difference between an image's downloaded size and its rendered size. For example: setting this value to 0.1 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate. A lower tolerance means images will render closer to their native size (thereby reducing rendering artifacts), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.
By default this rate is set to 8 percent, which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by passing a positive numeric value to `width_tolerance` within the `options` keyword argument:
```rb
-client = Imgix::Client.new(domain: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
+client = Imgix::Client.new(domain: 'testing.imgix.net', secure_url_token: 'MYT0KEN')
client.path('image.jpg').to_srcset(options: { width_tolerance: 0.20 })
```
In this case, the `width_tolerance` is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair:
@@ -146,11 +155,11 @@
### Minimum and Maximum Width Ranges
If the exact number of minimum/maximum physical pixels that an image will need to be rendered at is known, a user can specify them by passing an integer via `min_width` and/or `max_width` to the `options` keyword parameters:
```rb
-client = Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
+client = Imgix::Client.new(domain: 'testing.imgix.net')
client.path('image.jpg').to_srcset(options: { min_width: 500, max_width: 2000 })
```
Will result in a smaller, more tailored srcset.
@@ -179,11 +188,11 @@
This behavior will respect any overriding `q` value passed in as a parameter. Additionally, it can be disabled altogether by passing `options: { disable_variable_quality: true }` to `Imgix:Path#to_srcset`.
This behavior specifically occurs when a [fixed-size image](https://github.com/imgix/imgix-rb#fixed-image-rendering) is rendered, for example:
```rb
-srcset = Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
+srcset = Imgix::Client.new(domain: 'testing.imgix.net')
.path('image.jpg')
.to_srcset(w:100)
```
will generate a srcset with the following `q` to `dpr` mapping:
@@ -221,9 +230,9 @@
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', include_library_param: false )
```
## Contributing
-See the [contributing guide](Contributing.markdown).
+See the [contributing guide](CONTRIBUTING.md).
## License
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fimgix%2Fimgix-rb?ref=badge_large)