Mjml.Net 1.0.2

MJML.NET

A blazingly-fast unofficial port of MJML 4 (by MailJet) to .NET 6.

Introduction

MJML is a markup language created by Mailjet and designed to reduce the pain of coding a responsive email. Its semantic syntax makes the language easy and straightforward while its rich standard components library shortens your development time and lightens your email codebase. MJML’s open-source engine takes care of translating the MJML you wrote into responsive HTML.

Usage

Firstly, you'll need to reference the MJML.NET NuGet Package into your project.

PM > Install-Package Mjml.Net

Secondly, include MJML.NET namespace into your project.

using Mjml.Net;

Finally, the boilerplate code.

public static void Main (string[] args) {
    var mjmlRenderer = new MjmlRenderer();

    string text = @"
<mjml>
    <mj-head>
        <mj-title>Hello World Example</mj-title>
    </mj-head>
    <mj-body>
        <mj-section>
            <mj-column>
                <mj-text>
                    Hello World!
                </mj-text>
            </mj-column>
        </mj-section>
    </mj-body>
</mjml>";

    var html = mjmlRenderer.Render(text, new MjmlOptions {
        Beautify = false
    }).Html;
}

Options

You can also specify options to the MJML parser.

Supported Components

MJML.NET tries to implement all functionality 1-2-1 with the MJML 4 project. However, due to JavaScript not being a typed language this means there has been considerate refactoring to the code to make it more aligned with C# typed requirements.

Benchmarks

Performance was one of the key focuses for this project. We're aiming to support high througput while mainintaing low memory footprint. Below are the benchmarks for every public MJML template compiled (beautified and minified).

Important: These tests do not include loading or saving the template from/to disk.

If you'd like to run the benchmarks your self then you can run the Mjml.Net.Benchmarks project in release mode.

BenchmarkDotNet

> .\Mjml.Net.Benchmark.exe

Profiler

> .\Mjml.Net.Benchmark.exe -p -i 100

Benchmark Specs

BenchmarkDotNet=v0.13.1, OS=Windows 10.0.19043.1586 (21H1/May2021Update)
Intel Core i7-4790 CPU 3.60GHz (Haswell), 1 CPU, 8 logical and 4 physical cores
.NET SDK=6.0.101
  [Host]     : .NET 6.0.1 (6.0.121.56705), X64 RyuJIT
  Job-YRBKPS : .NET 6.0.1 (6.0.121.56705), X64 RyuJIT

Jit=RyuJit  Platform=X64  IterationCount=100 

Benchmark Key

MjmlTemplateFilePath : Value of the 'MjmlTemplateFilePath' parameter
Mean                 : Arithmetic mean of all measurements
Error                : Half of 99.9% confidence interval
StdDev               : Standard deviation of all measurements
Median               : Value separating the higher half of all measurements (50th percentile)
Allocated            : Allocated memory per single operation (managed only, inclusive, 1KB = 1024B)
1 us                 : 1 Microsecond (0.000001 sec)

Benchmark Results

All times are in μs (1ms = 1000 μs)

Known Issues

Unknown HTML Entity

We are aware with an issue where by using HTML Character Entities (e.g. ©) are unknown and throw an unhandled exception during the rendering of the MJML document. This is because we use XmlReader as the main driver for parsing the MJML document.

The solution is to change the HTML Character Entity Names (e.g. ©) to there corresponding HTML Character Entity Number (e.g. ©) in the MJML document. Here are some of the common HTML Character Entities:

Non-encoded URL

We are aware of an issue with non-encoded URL's being recognized as character entities leading to an exception. This is because we use XmlReader as the main driver for parsing the MJML document. This solution is to URL encode all of the URLs in the template.

Contribution

We really appreciate any contribution to the project to help provide a native version of MJML to C#. Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Appreciations

Once again, it's good to share some appreciation to the projects that make MJML.NET possible.

• MJML
• MJML.NET V1
• AngleSharp