{"id":13395001,"url":"https://github.com/fphilipe/premailer-rails","last_synced_at":"2025-04-27T04:17:53.681Z","repository":{"id":678576,"uuid":"1561299","full_name":"fphilipe/premailer-rails","owner":"fphilipe","description":"CSS styled emails without the hassle.","archived":false,"fork":false,"pushed_at":"2024-06-17T05:56:17.000Z","size":339,"stargazers_count":1720,"open_issues_count":12,"forks_count":256,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-16T00:02:28.940Z","etag":null,"topics":["css","email","gem","inline-css","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fphilipe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-04-03T00:05:17.000Z","updated_at":"2025-04-13T09:40:48.000Z","dependencies_parsed_at":"2024-06-17T06:59:22.362Z","dependency_job_id":null,"html_url":"https://github.com/fphilipe/premailer-rails","commit_stats":{"total_commits":333,"total_committers":57,"mean_commits":5.842105263157895,"dds":"0.43843843843843844","last_synced_commit":"a1974add753272205682c82175a46ca01da05efd"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fpremailer-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fpremailer-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fpremailer-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fphilipe%2Fpremailer-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fphilipe","download_url":"https://codeload.github.com/fphilipe/premailer-rails/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249838247,"owners_count":21332562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","email","gem","inline-css","rails","ruby"],"created_at":"2024-07-30T17:01:38.800Z","updated_at":"2025-04-25T15:53:09.983Z","avatar_url":"https://github.com/fphilipe.png","language":"Ruby","funding_links":[],"categories":["Ruby","Email","Gems"],"sub_categories":["Articles"],"readme":"# premailer-rails\n\nCSS styled emails without the hassle.\n\n[![Build Status][build-image]][build-link]\n[![Gem Version][gem-image]][gem-link]\n[![Code Climate][gpa-image]][gpa-link]\n\n## Introduction\n\nThis gem is a drop in solution for styling HTML emails with CSS without having\nto do the hard work yourself.\n\nStyling emails is not just a matter of linking to a stylesheet. Most clients,\nespecially web clients, ignore linked stylesheets or `\u003cstyle\u003e` tags in the HTML.\nThe workaround is to write all the CSS rules in the `style` attribute of each\ntag inside your email. This is a rather tedious and hard to maintain approach.\n\nPremailer to the rescue! The great [premailer] gem applies all CSS rules to each\nmatching HTML element by adding them to the `style` attribute. This allows you\nto keep HTML and CSS in separate files, just as you're used to from web\ndevelopment, thus keeping your sanity.\n\nThis gem is an adapter for premailer to work with [actionmailer] out of the box.\nActionmailer is the email framework used in Rails, which also works outside of\nRails. Although premailer-rails has certain Rails specific features, **it also\nworks in the absence of Rails** making it compatible with other frameworks such\nas sinatra.\n\n## How It Works\n\npremailer-rails works with actionmailer by registering a delivery hook. This\ncauses all emails that are delivered to be processed by premailer-rails. This\nmeans that by simply including premailer-rails in your `Gemfile` you'll get\nstyled emails without having to set anything up.\n\nWhenever premailer-rails processes an email, it collects the URLs of all linked\nstylesheets (`\u003clink rel=\"stylesheet\" href=\"css_url\"\u003e`). Then, for each of these\nURLs, it tries to get the content through a couple of strategies. As long as\na strategy does not return anything, the next one is used. The strategies\navailable are:\n\n-   `:filesystem`: If there's a file inside `public/` with the same path as in\n    the URL, it is read from disk. E.g. if the URL is\n    `http://cdn.example.com/assets/email.css` the contents of the file located\n    at `public/assets/email.css` gets returned if it exists.\n\n-   `:asset_pipeline`: If Rails is available and the asset pipeline is enabled,\n    the file is retrieved through the asset pipeline. E.g. if the URL is\n    `http://cdn.example.com/assets/email-fingerprint123.css`, the file\n    `email.css` is requested from the asset pipeline. That is, the fingerprint\n    and the prefix (in this case `assets` is the prefix) are stripped before\n    requesting it from the asset pipeline.\n\n-   `:network`: As a last resort, the URL is simply requested and the response\n    body is used. This is useful when the assets are not bundled in the\n    application and only available on a CDN. On Heroku e.g. you can add assets\n    to your `.slugignore` causing your assets to not be available to the app\n    (and thus resulting in a smaller app) and deploy the assets to a CDN such\n    as S3/CloudFront.\n\nYou can configure which strategies you want to use as well as specify their\norder. Refer to the *Configuration* section for more on this.\n\nNote that the retrieved CSS is cached when the gem is running with Rails in\nproduction.\n\n## Installation\n\nSimply add the gem to your `Gemfile`:\n\n```ruby\ngem 'premailer-rails'\n```\n\npremailer-rails and premailer require a gem that is used to parse the email's\nHTML. For a list of supported gems and how to select which one to use, please\nrefer to the [*Adapter*\nsection](https://github.com/premailer/premailer#adapters) of premailer. Note\nthat there is no hard dependency from either gem so you should add one yourself.\nAlso note that this gem is only tested with [nokogiri].\n\n## Configuration\n\nPremailer itself accepts a number of options. In order for premailer-rails to\npass these options on to the underlying premailer instance, specify them\nas follows (in Rails you could do that in an initializer such as\n`config/initializers/premailer_rails.rb`):\n\n```ruby\nPremailer::Rails.config.merge!(preserve_styles: true, remove_ids: true)\n```\n\nFor a list of options, refer to the [premailer documentation]. The default\nconfigs are:\n\n```ruby\n{\n  input_encoding: 'UTF-8',\n  generate_text_part: true,\n  strategies: [:filesystem, :asset_pipeline, :network]\n}\n```\n\nIf you don't want to automatically generate a text part from the html part, set\nthe config `:generate_text_part` to false.\n\nNote that the options `:with_html_string` and `:css_string` are used internally\nby premailer-rails and thus will be overridden.\n\nIf you're using this gem outside of Rails, you'll need to call\n`Premailer::Rails.register_interceptors` manually in order for it to work. This\nis done ideally in some kind of initializer, depending on the framework you're\nusing.\n\npremailer-rails reads all stylesheet `\u003clink\u003e` tags, inlines the linked CSS\nand removes the tags. If you wish to ignore a certain tag, e.g. one that links to\nexternal fonts such as Google Fonts, you can add a `data-premailer=\"ignore\"`\nattribute.\n\n## Usage\n\npremailer-rails processes all outgoing emails by default. If you wish to skip\npremailer for a certain email, simply set the `:skip_premailer` header:\n\n```ruby\nclass UserMailer \u003c ActionMailer::Base\n  def welcome_email(user)\n    mail to: user.email,\n         subject: 'Welcome to My Awesome Site',\n         skip_premailer: true\n  end\nend\n```\n\nNote that the mere presence of this header causes premailer to be skipped, i.e.,\neven setting `skip_premailer: false` will cause premailer to be skipped. The\nreason for that is that the `skip_premailer` is a simple header and the value is\ntransformed into a string, causing `'false'` to become truthy.\n\nEmails are only processed upon delivery, i.e. when calling `#deliver` on the\nemail, or when [previewing them in\nrails](http://api.rubyonrails.org/v4.1.0/classes/ActionMailer/Base.html#class-ActionMailer::Base-label-Previewing+emails).\nIf you wish to manually trigger the inlining, you can do so by calling the hook:\n\n```ruby\nmail = SomeMailer.some_message(args)\nPremailer::Rails::Hook.perform(mail)\n```\n\nThis will modify the email in place, useful e.g. in tests.\n\n## Supported Rails Versions\n\nThis gem is tested on Rails versions 5 through 7.\n\nFor Rails 7, it support both the classical Sprockets asset pipeline as well as the new [Propshaft](https://github.com/rails/propshaft) gem.\n\nIf you're looking to integrate with Webpacker, check out [these instructions](https://github.com/fphilipe/premailer-rails/issues/232#issuecomment-839819705).\n\n## Small Print\n\n### Author\n\nPhilipe Fatio ([@fphilipe][fphilipe twitter])\n\n### License\n\npremailer-rails is released under the MIT license. See the [license file].\n\n[build-image]: https://github.com/fphilipe/premailer-rails/actions/workflows/test.yml/badge.svg\n[build-link]:  https://github.com/fphilipe/premailer-rails/actions/workflows/test.yml\n[gem-image]:   https://badge.fury.io/rb/premailer-rails.svg\n[gem-link]:    https://rubygems.org/gems/premailer-rails\n[gpa-image]:   https://codeclimate.com/github/fphilipe/premailer-rails.svg\n[gpa-link]:    https://codeclimate.com/github/fphilipe/premailer-rails\n[tip-image]:   https://rawgithub.com/twolfson/gittip-badge/0.1.0/dist/gittip.svg\n[tip-link]:    https://www.gittip.com/fphilipe/\n\n[premailer]:    https://github.com/premailer/premailer\n[actionmailer]: https://github.com/rails/rails/tree/main/actionmailer\n[nokogiri]:     https://github.com/sparklemotion/nokogiri\n\n[premailer documentation]: https://www.rubydoc.info/gems/premailer/Premailer:initialize\n\n[fphilipe twitter]: https://twitter.com/fphilipe\n[license file]:     LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphilipe%2Fpremailer-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffphilipe%2Fpremailer-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffphilipe%2Fpremailer-rails/lists"}