MJML Ruby

[!] REQUIRES NODEJS

MJML parser and template engine for Ruby. Allows to create email templates without mess.

Install

Add to Gemfile:

gem 'mjml-ruby', '~> 0.4', require: 'mjml'

$ gem install mjml-ruby

Install NodeJS and MJML (both installations will works local and global).

$ npm install -g mjml@^3.0.0
$ bundle install

Usage

MJML v3

MJML v3 had added validation for templates and it breaks mjml-ruby v0.2.x if your template was invalid. mjml-ruby > v0.3.x has validation_level option(:soft by default) and allows to use old templates with v3. All validation errors will be logged.

Example:

MJML.configure do |config|
  config.validation_level = :soft # :skip/:soft/:strict
end

With Rails

<!-- app/views/layouts/mailer.html.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <%= yield %>
    </mj-container>
  </mj-body>
</mjml>

<!-- app/views/welcome_mailer/welcome.html.mjml -->

<mj-text>Hello, <%= @user.name %></mj-text>

class WelcomeMailer < ApplicationMailer
  def welcome(user)
    @user = user
    mail(to: @user.email, subject: 'Welcome')
  end
end

With Tilt

<!-- templates/hello.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <mj-text>Hello, world!</mj-text>
    </mj-container>
  </mj-body>
</mjml>

require 'tilt'
require 'mjml'

template = Tilt.new('templates/hello.mjml')
template.render # returns compiled HTML

With mail gem

<!-- hello.mjml -->

<mjml>
  <mj-body>
    <mj-container>
      <mj-text>Hello, world!</mj-text>
    </mj-container>
  </mj-body>
</mjml>

require 'mail'
require 'mjml'

template = File.open('hello.mjml', 'rb') { |f| MJML::Parser.new.call(f) }

Mail.deliver do
  from 'example@mail.com'
  to 'example@mail.com'
  subject 'Hello'
  body template
end

Configuration

# Change default mjml executable

# Regular Ruby
MJML.configure do |config|
  config.bin_path = '/usr/bin/env mjml'
  config.logger = YourLogger.new(STDOUT)
  config.minify_output = true
  config.validation_level = :soft
end

# Rails
Rails.application.configure do
  config.mjml.bin_path = '/usr/bin/env mjml'
  config.mjml.logger = MJML::Logger.setup!(STDOUT)
  config.mjml.minify_output = true
  config.mjml.validation_level = :soft
end

Deprecations

v0.3

config.debug = true is deprecated. If you are using default MJML Logger use config.logger.level = ::Logger::DEBUG instead.

TODO

Create parser
Make it configurable
Create Tilt interface
Create Sprockets interface
Create Railtie
Setup Travis
Add usage guide
Fix tests on CI
Add more tests
Improove docs

mjml-ruby

Development