How do I skip URL rewriting on specific elements in Roadie?

Add a data-roadie-ignore attribute to the element, like . This prevents URL rewriting while still allowing CSS inlining on that element.

Roadie vs Premailer: which is better for Ruby email templates?

Roadie offers more flexible asset providers and partial document support, while Premailer is tightly integrated with Rails. Choose Roadie for custom asset pipelines or non-Rails projects, Premailer for simpler Rails setups.

Why does Roadie change my HTML markup?

Roadie uses Nokogiri to parse and regenerate HTML, which can normalize entities or alter structures. This is a known limitation, especially with HTML5 elements, as mentioned in the FAQ.

How to handle :hover states in emails with Roadie?

Roadie preserves :hover selectors in a separate style block, but due to specificity issues, you may need to add !important to ensure they apply over inlined styles, as explained in the README.

Can Roadie work with Rails asset pipeline?

Yes, through custom asset providers or the roadie-rails gem for integration. Roadie itself is framework-agnostic and can be configured to access assets from Rails' pipeline.

What should I do about Roadie segmentation faults?

Segfaults are typically from Nokogiri's C dependencies. Upgrade libxml2 on your system and reinstall Nokogiri, as recommended in the README's troubleshooting section.

Open-Awesome

Roadie

MITRuby

A Ruby gem that inlines CSS styles and rewrites relative URLs in HTML emails for better client compatibility.

GitHub

1.3k stars82 forks0 contributors

What is Roadie?

Roadie is a Ruby gem that processes HTML emails by inlining CSS styles directly into HTML elements and rewriting relative URLs to absolute ones. It solves the problem of inconsistent CSS support across email clients, allowing developers to write maintainable stylesheets while ensuring emails render correctly.

Target Audience

Ruby developers and teams building HTML email templates for newsletters, transactional emails, or marketing campaigns who need reliable styling across diverse email clients.

Value Proposition

Roadie automates the tedious and error-prone process of manually inlining CSS and fixing URLs, saving development time and reducing email rendering issues. Its flexible provider system and configurability make it adaptable to various project workflows.

Overview

Making HTML emails comfortable for the Ruby rockstars

Use Cases

Best For

Generating HTML email templates with consistent styling across clients
Automating CSS inlining in Ruby-based email pipelines
Handling relative asset paths in emails for different deployment environments
Integrating email styling with asset pipelines or custom storage systems
Maintaining reusable CSS while ensuring client compatibility
Processing email HTML fragments or partial templates

Not Ideal For

Email designs heavily reliant on HTML5 elements or advanced CSS animations like @keyframes
High-throughput email systems where minimal processing overhead is critical
Teams requiring active community support and frequent updates for new email client quirks
Projects where dynamic CSS states (e.g., :hover) are essential and cannot be augmented with !important declarations

Pros & Cons

Pros

Automated CSS Inlining

Inlines CSS while respecting selector specificity and !important rules, ensuring styles apply correctly across email clients as described in the README.

Configurable URL Rewriting

Rewrites relative URLs to absolute ones based on customizable host and protocol settings, with per-element control via data-roadie-ignore attributes.

Flexible Asset Providers

Supports loading stylesheets from filesystems, networks, or custom sources through a provider system, allowing integration with various asset pipelines.

Partial Document Support

Handles both full HTML documents and fragments, automatically adding or omitting the HTML skeleton as needed for different use cases.

Cons

Passive Maintenance Mode

The project is in passive maintenance, meaning fewer updates and slower responses to bugs or evolving email client standards, as noted in the README.

Nokogiri Dependency Quirks

Relies on Nokogiri for HTML parsing, which can alter markup (e.g., handling of or lack of HTML5 support) and may cause stability issues like segmentation faults.

Dynamic CSS Specificity Issues

Uninlinable CSS such as :hover selectors is preserved but often requires manual !important declarations to overcome specificity conflicts, adding complexity.

Frequently Asked Questions

Related Projects

Postal

📮 A fully featured open source mail delivery platform for incoming & outgoing e-mail

Stars16,483

Forks1,232

Last commit4 days ago

letter_opener

Preview mail in the browser instead of sending.

Stars3,837

Forks242

Last commit7 days ago

Mail

A Really Ruby Mail Library

Stars3,665

Forks936

Last commit6 months ago

premailer-rails

CSS styled emails without the hassle.

Stars1,753

Forks256

Last commit1 year ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub