mjml-rb 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c04515032bc1da0a7fcbbad05d5d2b8bb10f684cb34e3b25920f96e10e63207
+  data.tar.gz: 778c683334aecab61498fde20ea06ba55e417c5080fd1776dacf5668f609988e
+SHA512:
+  metadata.gz: 3c2b46d74bb5804fd9db901c529aec0fd2a4d9cb9b8b97872ce5d7bef2fc22077cfa1b0471f368ab268b5c3d8b231e0cbc13f5b565da937692689233b98a55ae
+  data.tar.gz: 37e1b8ce0fa0134c5cbe41e8977fb3f0722dcbcea69728f2b810a1bf615a81691f27fa55805ccd52f37b23c078d957ed3fbc388f9898a9cad4fd667773fe2781

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Andriichuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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.

data/README.md

@@ -0,0 +1,79 @@
+# MJML Ruby Implementation
+
+> **⚠️ EXPERIMENTAL — USE AT YOUR OWN RISK**
+>
+> This is an **unofficial, experimental** Ruby port of the MJML email framework.
+> It is **not affiliated with or endorsed by the MJML team**.
+> The output HTML may differ from the reference `mjml` npm package in subtle ways,
+> and not all components or attributes are fully implemented yet.
+> **Do not use in production without thorough testing of every template against
+> the official npm renderer.** API and output format may change without notice.
+> No warranty of any kind is provided.
+
+This directory contains a Ruby-first implementation of the main MJML user-facing tooling:
+
+- library API compatible with `mjml2html`
+- command-line interface (`mjml`)
+- migration and validation commands
+- pure Ruby parser + AST + renderer (no external native renderer dependency)
+
+## Quick start
+
+```bash
+bundle install
+bundle exec ruby -Ilib -e 'require "mjml-rb"; puts MjmlRb.mjml2html("<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>")[:html]'
+```
+
+## CLI usage
+
+```bash
+bundle exec bin/mjml example.mjml -o output.html
+bundle exec bin/mjml --validate example.mjml
+bundle exec bin/mjml --migrate old.mjml -s
+```
+
+## Migration status
+
+The table below tracks current JS-to-Ruby migration status for MJML components in this repo.
+
+| Component | Status | Notes |
+| --- | --- | --- |
+| `mj-body` | migrated | Ruby component exists and matches the upstream `mj-body` behavior currently vendored in `lib/mjml-rb/components/mjml-body`. |
+| `mj-section` | migrated | Implemented in `section.rb`. |
+| `mj-wrapper` | migrated | Implemented via `section.rb`. |
+| `mj-column` | migrated | Implemented in `column.rb`. |
+| `mj-group` | migrated | Rendered directly by the renderer. |
+| `mj-text` | migrated | Implemented in `text.rb`. |
+| `mj-image` | migrated | Implemented in `image.rb`. |
+| `mj-button` | migrated | Implemented in `button.rb`. |
+| `mj-divider` | migrated | Implemented in `divider.rb`. |
+| `mj-table` | migrated | Implemented in `table.rb`. |
+| `mj-social` | migrated | Implemented in `social.rb`. |
+| `mj-social-element` | migrated | Implemented in `social.rb`. |
+| `mj-accordion` | migrated | Implemented in `accordion.rb`. |
+| `mj-accordion-element` | migrated | Implemented in `accordion.rb`. |
+| `mj-accordion-title` | migrated | Implemented in `accordion.rb`. |
+| `mj-accordion-text` | migrated | Implemented in `accordion.rb`. |
+| `mj-spacer` | migrated | Implemented in `spacer.rb`. |
+| `mj-hero` | migrated | Implemented in `hero.rb` with fixed/fluid modes, inner content wrapper, and Outlook VML background fallback. |
+| `mj-navbar` | migrated | Implemented in `navbar.rb`, including `base-url` propagation and breakpoint-aware hamburger CSS. |
+| `mj-navbar-link` | migrated | Implemented in `navbar.rb` as an ending-tag navbar child component. |
+| `mj-raw` | partial | Supported as passthrough content, but not as a dedicated migrated component. |
+| `mj-head` | partial | Core tags such as `mj-title`, `mj-preview`, `mj-style`, `mj-font`, and `mj-attributes` are supported. |
+| `mj-attributes` | partial | `mj-all`, `mj-class`, and per-tag defaults are supported. |
+| `mj-all` | partial | Supported through `mj-attributes`. |
+| `mj-class` | partial | Supported through `mj-attributes`. |
+| `mj-title` | partial | Supported through head context. |
+| `mj-preview` | partial | Supported through head context. |
+| `mj-style` | partial | Supported, including inline CSS application. |
+| `mj-font` | partial | Supported for font link injection. |
+| `mj-carousel` | not migrated | Declared in dependency rules but no renderer implementation yet. |
+| `mj-carousel-image` | not migrated | Declared in dependency rules but no renderer implementation yet. |
+| `mj-breakpoint` | migrated | Supported in `mj-head` and used to control desktop column media-query widths. |
+| `mj-html-attributes` | migrated | Supported in `mj-head` and applied to the rendered HTML via CSS selectors. |
+| `mj-selector` | migrated | Supported as the selector container for `mj-html-attribute` rules. |
+| `mj-html-attribute` | migrated | Supported for injecting custom HTML attributes into matched rendered nodes. |
+
+Remaining top-level migration work is mainly `mj-carousel` and `mj-carousel-image`, plus bringing the remaining renderer-owned partial implementations closer to upstream JS behavior.
+
+TODO: `mj-html-attributes` currently uses `Nokogiri` to parse rendered HTML and apply CSS-selector-based attribute injections. Rewrite this path to avoid `Nokogiri` if we want to keep the runtime dependency surface minimal.

data/bin/mjml

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "mjml-rb"
+
+exit(MjmlRb::CLI.new.run(ARGV))

data/lib/mjml-rb/ast_node.rb

@@ -0,0 +1,34 @@
+module MjmlRb
+  class AstNode
+    attr_reader :tag_name, :attributes, :children, :content, :line
+
+    def initialize(tag_name:, attributes: {}, children: [], content: nil, line: nil)
+      @tag_name = tag_name.to_s
+      @attributes = attributes.transform_keys(&:to_s)
+      @children = Array(children)
+      @content = content
+      @line = line
+    end
+
+    def text?
+      @tag_name == "#text"
+    end
+
+    def comment?
+      @tag_name == "#comment"
+    end
+
+    def element?
+      !text? && !comment?
+    end
+
+    def text_content
+      return @content.to_s if text?
+      @children.map(&:text_content).join
+    end
+
+    def element_children
+      @children.select(&:element?)
+    end
+  end
+end

data/lib/mjml-rb/cli.rb

@@ -0,0 +1,305 @@
+require "json"
+require "optparse"
+require "pathname"
+require "time"
+
+require_relative "compiler"
+require_relative "migrator"
+require_relative "version"
+
+module MjmlRb
+  class CLI
+    class CLIError < StandardError; end
+
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv = ARGV)
+      raw_argv = argv.dup
+      argv, inline_config = extract_inline_config(raw_argv)
+      options = default_options
+
+      parser = option_parser(options, inline_config)
+      parser.parse!(argv)
+      options[:positional] = argv
+
+      input_mode, input_values = resolve_input(options)
+      output_mode = resolve_output(options)
+      config = options[:config]
+
+      case input_mode
+      when :watch
+        watch_files(input_values, config, options[:output])
+        0
+      when :stdin
+        mjml = $stdin.read
+        processed = process_input({ file: nil, mjml: mjml }, input_mode, config)
+        emit_results([processed], output_mode, options)
+      else
+        inputs = load_inputs(input_values)
+        raise CLIError, "No input files found" if inputs.empty?
+
+        processed = inputs.map { |input| process_input(input, input_mode, config) }
+        emit_results(processed, output_mode, options)
+      end
+    rescue CLIError => e
+      @stderr.puts("\nCommand line error:")
+      @stderr.puts(e.message)
+      1
+    rescue OptionParser::ParseError => e
+      @stderr.puts(e.message)
+      1
+    end
+
+    private
+
+    def default_options
+      {
+        read: [],
+        migrate: [],
+        validate: [],
+        watch: [],
+        stdin: false,
+        stdout: false,
+        output: nil,
+        no_stdout_file_comment: false,
+        config: {
+          beautify: true,
+          minify: false
+        }
+      }
+    end
+
+    def option_parser(options, inline_config)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: mjml [options] [files]"
+
+        opts.on("-r", "--read FILES", Array, "Compile MJML files") { |v| options[:read].concat(v) }
+        opts.on("-m", "--migrate FILES", Array, "Migrate MJML3 files") { |v| options[:migrate].concat(v) }
+        opts.on("-v", "--validate FILES", Array, "Validate MJML files") { |v| options[:validate].concat(v) }
+        opts.on("-w", "--watch FILES", Array, "Watch and compile files when modified") { |v| options[:watch].concat(v) }
+        opts.on("-i", "--stdin", "Read MJML from stdin") { options[:stdin] = true }
+        opts.on("-s", "--stdout", "Output HTML to stdout") { options[:stdout] = true }
+        opts.on("-o", "--output PATH", "Output file or directory") { |v| options[:output] = v }
+        opts.on("-c", "--config KEY=VALUE", "Compiler config key/value") do |entry|
+          key, value = parse_key_value(entry)
+          options[:config][normalize_key(key)] = parse_typed_value(value)
+        end
+        opts.on("--noStdoutFileComment", "Skip file comment header on stdout") do
+          options[:no_stdout_file_comment] = true
+        end
+        opts.on("-V", "--version", "Show version") do
+          @stdout.puts("mjml-ruby #{MjmlRb::VERSION}")
+          raise SystemExit, 0
+        end
+        opts.on("-h", "--help", "Show help") do
+          @stdout.puts(opts)
+          raise SystemExit, 0
+        end
+      end.tap do
+        inline_config.each do |key, value|
+          options[:config][normalize_key(key)] = value
+        end
+      end
+    end
+
+    def extract_inline_config(argv)
+      config = {}
+      remaining = []
+
+      argv.each do |arg|
+        if arg.start_with?("--config.")
+          key, value = parse_key_value(arg.sub("--config.", ""))
+          config[key] = parse_typed_value(value)
+        else
+          remaining << arg
+        end
+      end
+
+      [remaining, config]
+    end
+
+    def parse_key_value(input)
+      key, value = input.split("=", 2)
+      raise CLIError, "Invalid config entry: #{input}" if key.to_s.empty?
+      [key, value]
+    end
+
+    def parse_typed_value(value)
+      return true if value.nil?
+      return false if value == "false"
+      return true if value == "true"
+      return value.to_i if value.match?(/\A-?\d+\z/)
+      return value.to_f if value.match?(/\A-?\d+\.\d+\z/)
+
+      begin
+        JSON.parse(value)
+      rescue JSON::ParserError
+        value
+      end
+    end
+
+    def normalize_key(key)
+      key.to_s.tr("-", "_").to_sym
+    end
+
+    def resolve_input(options)
+      inputs = {}
+      inputs[:read] = options[:read] unless options[:read].empty?
+      inputs[:migrate] = options[:migrate] unless options[:migrate].empty?
+      inputs[:validate] = options[:validate] unless options[:validate].empty?
+      inputs[:watch] = options[:watch] unless options[:watch].empty?
+      inputs[:stdin] = true if options[:stdin]
+      inputs[:read] = options[:positional] unless options[:positional].empty?
+
+      raise CLIError, "No input argument received" if inputs.empty?
+      raise CLIError, "Too many input arguments received" if inputs.keys.size > 1
+
+      key = inputs.keys.first
+      [key, inputs[key]]
+    end
+
+    def resolve_output(options)
+      outputs = []
+      outputs << :output if !options[:output].nil?
+      outputs << :stdout if options[:stdout]
+
+      raise CLIError, "Too many output arguments received" if outputs.size > 1
+      outputs.first || :stdout
+    end
+
+    def load_inputs(patterns)
+      expand_paths(Array(patterns)).map { |path| { file: path, mjml: File.read(path) } }
+    rescue Errno::ENOENT => e
+      raise CLIError, "Cannot read file: #{e.message}"
+    end
+
+    def expand_paths(patterns)
+      paths = patterns.flat_map { |pattern| Dir.glob(pattern, File::FNM_EXTGLOB) }
+      paths.uniq.select { |path| File.file?(path) }
+    end
+
+    def process_input(input, mode, config)
+      case mode
+      when :migrate
+        html = Migrator.new.migrate(input[:mjml])
+        { file: input[:file], compiled: Result.new(html: html) }
+      when :validate
+        compiler = Compiler.new(config.merge(validation_level: "strict"))
+        { file: input[:file], compiled: compiler.compile(input[:mjml]) }
+      else
+        compiler = Compiler.new(config)
+        { file: input[:file], compiled: compiler.compile(input[:mjml]) }
+      end
+    end
+
+    def emit_results(processed, output_mode, options)
+      processed.each { |item| emit_errors(item[:compiled], item[:file]) }
+
+      invalid = processed.any? { |item| !item[:compiled].errors.empty? }
+      if options[:validate].any? && invalid
+        raise CLIError, "Validation failed"
+      end
+
+      case output_mode
+      when :stdout
+        print_stdout(processed, !options[:no_stdout_file_comment])
+      when :output
+        write_outputs(processed, options[:output])
+      else
+        raise CLIError, "Command line error: No output option available"
+      end
+
+      invalid ? 2 : 0
+    end
+
+    def emit_errors(result, file)
+      return if result.errors.empty?
+      result.errors.each do |error|
+        prefix = file ? "File: #{file}\n" : ""
+        @stderr.puts("#{prefix}#{error[:formatted_message] || error[:message]}")
+      end
+    end
+
+    def print_stdout(processed, add_file_comment)
+      processed.each do |entry|
+        output = +""
+        output << "<!-- FILE: #{entry[:file]} -->\n" if add_file_comment
+        output << entry[:compiled].html
+        output << "\n"
+        @stdout.write(output)
+      end
+    end
+
+    def write_outputs(processed, output_path)
+      if processed.size > 1 && !directory?(output_path) && output_path != ""
+        raise CLIError, "Multiple input files require an existing output directory or empty output path"
+      end
+
+      processed.each do |entry|
+        output_name = guess_output_name(entry[:file], output_path)
+        dir = File.dirname(output_name)
+        raise CLIError, "Output directory does not exist for path: #{output_name}" unless directory?(dir)
+
+        File.write(output_name, entry[:compiled].html)
+      end
+    end
+
+    def guess_output_name(input_file, output_path)
+      return replace_extension(File.basename(input_file)) if output_path.to_s.empty?
+      return File.join(output_path, replace_extension(File.basename(input_file))) if directory?(output_path)
+
+      output_path
+    end
+
+    def replace_extension(path)
+      return path.sub(/\.mjml\z/, ".html") if path.end_with?(".mjml")
+      return path if path.match?(/\.[^\/]+\z/)
+
+      "#{path}.html"
+    end
+
+    def directory?(path)
+      File.directory?(File.expand_path(path.to_s))
+    rescue StandardError
+      false
+    end
+
+    def watch_files(patterns, config, output_path)
+      files = expand_paths(Array(patterns))
+      raise CLIError, "No input files found" if files.empty?
+      if files.size > 1 && !directory?(output_path) && output_path != ""
+        raise CLIError, "Need an output directory when watching multiple files"
+      end
+
+      state = files.each_with_object({}) { |path, memo| memo[path] = file_mtime(path) }
+      @stdout.puts("Watching #{files.size} file(s)...")
+
+      loop do
+        files.each do |file|
+          current = file_mtime(file)
+          next if current.nil? || current <= state[file]
+
+          state[file] = current
+          begin
+            input = { file: file, mjml: File.read(file) }
+            processed = process_input(input, :read, config)
+            emit_results([processed], :output, output: output_path, no_stdout_file_comment: true, validate: [])
+            @stdout.puts("#{file} - Successfully compiled")
+          rescue StandardError => e
+            @stderr.puts("#{file} - Error while compiling file: #{e.message}")
+          end
+        end
+        sleep 0.5
+      end
+    end
+
+    def file_mtime(path)
+      File.mtime(path)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/mjml-rb/compiler.rb

@@ -0,0 +1,109 @@
+require_relative "result"
+require_relative "validator"
+require_relative "parser"
+require_relative "renderer"
+
+module MjmlRb
+  class Compiler
+    DEFAULT_OPTIONS = {
+      beautify: false,
+      minify: false,
+      keep_comments: true,
+      ignore_includes: false,
+      preprocessors: [],
+      validation_level: "soft",
+      file_path: ".",
+      actual_path: "."
+    }.freeze
+
+    def initialize(options = {})
+      @options = DEFAULT_OPTIONS.merge(symbolize_keys(options))
+      @parser = Parser.new
+      @validator = Validator.new(parser: @parser)
+      @renderer = Renderer.new
+    end
+
+    def mjml2html(mjml, options = {})
+      compile(mjml, options)
+    end
+
+    def compile(mjml, options = {})
+      merged = @options.merge(symbolize_keys(options))
+      ast = @parser.parse(
+        mjml,
+        keep_comments: merged[:keep_comments],
+        preprocessors: Array(merged[:preprocessors]),
+        ignore_includes: merged[:ignore_includes],
+        file_path: merged[:file_path],
+        actual_path: merged[:actual_path]
+      )
+
+      validation_errors = validate_if_needed(ast, merged)
+      return Result.new(errors: validation_errors) if strict_validation_failed?(merged, validation_errors)
+
+      html = @renderer.render(ast, merged)
+      result = Result.new(
+        html: post_process(html, merged),
+        errors: validation_errors,
+        warnings: []
+      )
+      result
+    rescue Parser::ParseError => e
+      Result.new(errors: [format_error(e.message, line: e.line)])
+    rescue StandardError => e
+      Result.new(errors: [format_error(e.message)])
+    end
+
+    private
+
+    def validate_if_needed(ast, options)
+      return [] if options[:validation_level].to_s == "skip"
+      @validator.validate(ast, options)
+    end
+
+    def strict_validation_failed?(options, validation_errors)
+      options[:validation_level].to_s == "strict" && !validation_errors.empty?
+    end
+
+    def post_process(html, options)
+      output = html.to_s.dup
+      output = strip_comments(output) unless options[:keep_comments]
+      output = beautify(output) if truthy?(options[:beautify])
+      output = minify(output) if truthy?(options[:minify])
+      output
+    end
+
+    def strip_comments(html)
+      html.gsub(/<!--.*?-->/m, "")
+    end
+
+    def beautify(html)
+      # Keep it deterministic without external formatters.
+      html.gsub(/>\s*</, ">\n<")
+    end
+
+    def minify(html)
+      html.gsub(/>\s+</, "><").gsub(/\s{2,}/, " ").strip
+    end
+
+    def truthy?(value)
+      return value if value == true || value == false
+      !(%w[false 0 no off].include?(value.to_s.strip.downcase))
+    end
+
+    def symbolize_keys(hash)
+      hash.each_with_object({}) do |(k, v), memo|
+        memo[k.to_s.tr("-", "_").to_sym] = v
+      end
+    end
+
+    def format_error(message, line: nil)
+      {
+        line: line,
+        message: message.to_s,
+        tag_name: nil,
+        formatted_message: message.to_s
+      }
+    end
+  end
+end