README.md in roadie-3.3.0 vs README.md in roadie-3.4.0
- old
+ new
@@ -2,14 +2,18 @@
======
[](http://travis-ci.org/#!/Mange/roadie)
[](https://codeclimate.com/github/Mange/roadie)
[](https://codecov.io/github/Mange/roadie?branch=master)
-[](http://badge.fury.io/rb/roadie)
+[](https://rubygems.org/gems/roadie)
+[][passive]
-**Note: This README details the 3.x version of Roadie. You might be using 2.x, which is much older and only for Rails.**
+|||
+|---|---|
+| :warning: | This gem is now in [passive maintenance mode][passive]. [(more)][passive] |
+
> Making HTML emails comfortable for the Ruby rockstars
Roadie tries to make sending HTML emails a little less painful by inlining stylesheets and rewriting relative URLs for you inside your emails.
@@ -33,11 +37,11 @@
* Writes CSS styles inline.
* Respects `!important` styles.
* Does not overwrite styles already present in the `style` attribute of tags.
* Supports the same CSS selectors as [Nokogiri](http://nokogiri.org/); use CSS3 selectors in your emails!
- * Keeps `:hover` and friends around in a separate `<style>` element.
+ * Keeps `:hover`, `@media { ... }` and friends around in a separate `<style>` element.
* Makes image urls absolute.
* Hostname and port configurable on a per-environment basis.
* Can be disabled on individual elements.
* Makes link `href`s and `img` `src`s absolute.
* Automatically adds proper HTML skeleton when missing; you don't have to create a layout for emails.
@@ -49,11 +53,11 @@
---------------
[Add this gem to your Gemfile as recommended by Rubygems](http://rubygems.org/gems/roadie) and run `bundle install`.
```ruby
-gem 'roadie', '~> 3.2'
+gem 'roadie', '~> 3.4'
```
You can then create a new instance of a Roadie document:
```ruby
@@ -72,10 +76,23 @@
Your document instance can be configured with several options:
* `url_options` - Dictates how absolute URLs should be built.
* `keep_uninlinable_css` - Set to false to skip CSS that cannot be inlined.
+* `merge_media_queries` - Set to false to not group media queries. Some users might prefer to not group rules within media queries because
+ it will result in rules getting reordered.
+ e.g.
+ ```css
+ @media(max-width: 600px) { .col-6 { display: block; } }
+ @media(max-width: 400px) { .col-12 { display: inline-block; } }
+ @media(max-width: 600px) { .col-12 { display: block; } }
+ ```
+ will become
+ ```css
+ @media(max-width: 600px) { .col-6 { display: block; } .col-12 { display: block; } }
+ @media(max-width: 400px) { .col-12 { display: inline-block; } }
+ ```
* `asset_providers` - A list of asset providers that are invoked when CSS files are referenced. See below.
* `external_asset_providers` - A list of asset providers that are invoked when absolute CSS URLs are referenced. See below.
* `before_transformation` - A callback run before transformation starts.
* `after_transformation` - A callback run after transformation is completed.
@@ -462,10 +479,16 @@
### What happened to my `@keyframes`?
The CSS Parser used in Roadie does not handle keyframes. I don't think any email clients do either, but if you want to keep on trying you can add them manually to a `<style>` element (or a separate referenced stylesheet) and [tell Roadie not to touch them](#referenced-stylesheets).
+### My `@media` queries are reordered, how can I fix this?
+
+Different `@media` query blocks with the same conditions are merged by default,
+which will change the order in some cases. You can disable this by setting
+`merge_media_queries` to `false`. (See *Install & Usage* section above).
+
### How do I get rid of the `<body>` elements that are added?
It sounds like you want to transform a partial document. Maybe you are building
partials or template fragments to later place in other documents. Use
`Document#transform_partial` instead of `Document#transform` in order to treat
@@ -551,5 +574,6 @@
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
[gpg]: https://gist.github.com/Mange/baf25e23e653a206ec2d#file-keybase-md
+[passive]: https://github.com/Mange/roadie/issues/155