Premailer README

What is this?

For the best HTML e-mail delivery results, CSS should be inline. This is a huge pain and a simple newsletter becomes un-managable very quickly. This gem is a solution.

• CSS styles are converted to inline style attributes
  • Checks style and link[rel=stylesheet] tags and preserves existing inline attributes
• Relative paths are converted to absolute paths
  • Checks links in href, src and CSS url('')
• CSS properties are checked against e-mail client capabilities
  • Based on the Email Standards Project's guides
• A plain text version is created (optional)

Installation

gem install premailer

Example

require 'premailer'

premailer = Premailer.new('http://example.com/myfile.html', warn_level: Premailer::Warnings::SAFE)

# Write the plain-text output (must come before to_inline_css)
File.write "output.txt", premailer.to_plain_text

# Write the HTML output
File.write "output.html", premailer.to_inline_css

# Output any CSS warnings
premailer.warnings.each do |w|
  puts "#{w[:message]} (#{w[:level]}) may not render properly in #{w[:clients]}"
end

The plain-text version excludes the contents of <style> and <script> elements, including styles retained in HTML with preserve_styles: true.

Adapters

1. nokogiri (default)
2. nokogiri_fast (20x speed, more memory)
3. nokogumbo

(hpricot adapter removed, use ~>1.9.0 version if you need it)

Picking an adapter:

Premailer::Adapter.use = :nokogiri_fast

When converting image CSS to HTML attributes, only float: left and float: right become align attributes. Other values, such as float: none, remain in the inline style because they have no equivalent HTML alignment.

Ruby Compatibility

See .github/workflows/actions.yml for which ruby versions are tested. JRuby support is close, contributors are welcome.

Premailer-specific CSS

Premailer looks for a few CSS attributes that make working with tables a bit easier.

CSS Attribute	Availability
-premailer-width	Available on table, th and td elements
-premailer-height	Available on table, tr, th and td elements
-premailer-cellpadding	Available on table elements
-premailer-cellspacing	Available on table elements
-premailer-align	Available on table elements
data-premailer="ignore"	Available on link and style elements. Premailer will ignore these elements entirely.

Each of these CSS declarations will be copied to appropriate element's attribute.

Background image URLs on tables are copied to the HTML background attribute. Gradients remain in inline CSS because that attribute only supports image URLs.

For example

table { -premailer-cellspacing: 5; -premailer-width: 500; }

will result in

<table cellspacing='5' width='500'>

Plain text version

Premailer can generate a plain text version of your HTML. Links and images will be inlined.

For example

<a href="https://example.com" >
  <img src="https://github.com/premailer.png" alt="Premailer Logo" />
</a>

will become

Premailer Logo ( https://example.com )

To ignore/omit a section of HTML content from the plain text version, wrap it with the following comments.

<!-- start text/html -->
<p>This will be omitted from the plain text version.</p>
<p>
  This is extremely helpful for <strong>removing email headers and footers</strong>
  that aren't needed in the text version.
</p>
<!-- end text/html -->

Configuration options

For example:

Premailer.new(
  html, # html as string
  with_html_string: true,
  drop_unmergeable_css_rules: true
)

available options

For the current options, see the constructor source.

Verbose diagnostics are written to stderr. The command-line tool keeps its generated HTML on stdout, including when --verbose is enabled.

Loading CSS from local/private hosts

css_parser 3+ blocks fetching remote CSS (<link>, @import) from hosts that resolve to loopback/private IPs or do not resolve at all, to prevent SSRF. Those styles are silently dropped (unless io_exceptions: true). To allow them, when the html is trusted:

Premailer.new(html, with_html_string: true, allow_local_network: true)

Subresource Integrity

Remote <link rel="stylesheet"> tags with an integrity attribute are verified before inlining. A stylesheet whose hash does not match is dropped (or raises CssParser::IntegrityError with io_exceptions: true).

Support for CSS variables

The gem does not automatically replace CSS variables with their static values.

For example, if a variable is used to set the font-weight of an h1 element, the result will be

<h1 style="
  font-size:3rem;
  font-weight:var(--bulma-content-heading-weight);">
  Title</h1>

This causes the font-weight value to be the CSS variable call var(--bulma-content-heading-weight); instead of its static value.

Replace CSS variable calls with their static values

The following section instructs how to replace CSS variables with their static value in the context of a Ruby on Rails application.

Install the postcss-css-variables plugin for PostCSS to process the CSS variables.

yarn add postcss postcss-cli postcss-css-variables

To configure the plugin, create the file postcss.config.js in the root directory with the content:

This is the beginning of the README. Read the rest at the original. Read the full README ↗