MJML.NET

repository·main·Indexed 42 days ago

https://github.com/sebastianstehle/mjml-net

A high-performance unofficial .NET 6 to 9 port of MJML 4 used to translate MJML markup into responsive HTML for email development. It provides the MjmlRenderer and MjmlOptions for customizing rendering behavior, including support for core, head, and body components. Features include an experimental AngleSharp-based post-processor for inline styles and HTML attributes, and a transition to a standard HTML parser in version 2.0.0 to better handle non-valid XML.

Tokens: 2.2K
Snippets: 8
Records: 12
Agent score: 5%

What's inside MJML.NET

How to handle non-valid XML in MJML (Pre-v2.0.0)
main
MJML syntax is not always strictly valid XML.
For Version 2.0.0 and later: The engine uses an HTML parser that follows official standards and can accept various HTML inputs without manual sanitization.
For versions older than 2.0.0: You must sanitize the MJML string before rendering using the FixXML method to ensure the XML parser works correctly. It is recommended to store both the original and the sanitized version if saving to a database.
```
// Legacy approach for versions < 2.0.0
var xml = mjmlRenderer.FixXML(text, options);
var (html, errors) = mjmlRenderer.Render(xml, options);
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md

Render MJML to HTML with MjmlRenderer

main

To render MJML markup into responsive HTML, instantiate an MjmlRenderer, provide your MJML string, and pass an MjmlOptions object. The Render method returns a tuple containing the resulting html string and any errors encountered during parsing.

using Mjml.Net;

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 options = new MjmlOptions
    {
        Beautify = false
    };

    var (html, errors) = mjmlRenderer.Render(text, options);
}

Run the Mjml.Net vs. MJML (JavaScript) benchmark
main
To generate the comparison report between Mjml.Net and the original MJML (JavaScript) renderer, run the Mjml.Net.Compare project using the .NET CLI in Release mode.
Note: This report is automatically generated and should not be edited manually. The benchmark compares in-process rendering performance (excluding beautify, minify, and validation) across various MJML templates.
```
dotnet run -c Release --project Mjml.Net.Compare
```
https://github.com/sebastianstehle/mjml-net/blob/main/benchmark.md
Compare Mjml.Net performance against MJML (JavaScript)
main
You can reproduce the performance comparison between Mjml.Net and the original MJML (Node.js) using the Mjml.Net.Compare project. The comparison measures the time taken to render various benchmark templates in-process.
```
dotnet run -c Release --project Mjml.Net.Compare
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Use Inline Styles and HTML Attributes via Post-Processors
main
MJML supports inline styles and HTML attributes, but these are expensive features that require a post-processing step after the initial rendering. MJML.NET implements this using the AngleSharp library via a separate NuGet package.
Warning: EXPERIMENTAL FEATURE. There are known bugs in the CSS library; it is not recommended for production use yet.
To use this feature:
1. Install the Mjml.Net.PostProcessors package.
2. Add AngleSharpPostProcessor.Default to the PostProcessors list in your MjmlOptions.
3. Call mjmlRenderer.AddHtmlAttributes() on your renderer instance.
4. Crucial: You must use the asynchronous method variants (e.g., RenderAsync) to run post-processors, as they may use async methods.
```
// 1. Install-Package Mjml.Net.PostProcessors

var options = new MjmlOptions
{
    PostProcessors = [AngleSharpPostProcessor.Default]
};

var mjmlRenderer = new MjmlRenderer();

// 2. Enable HTML attributes post-processing
mjmlRenderer.AddHtmlAttributes();

// 3. Use the ASYNC method to ensure post-processors run
var (html, errors) = await mjmlRenderer.RenderAsync(text, options);
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Run MJML.NET benchmarks
main
To run the internal performance benchmarks for the Mjml.Net.Benchmarks project, execute it in release mode. Note that these tests measure rendering performance and do not include disk I/O for loading or saving templates.
```
dotnet run -c Release --project Mjml.Net.Benchmarks
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Install MJML.NET via NuGet
main
To use MJML.NET in your .NET project, install the Mjml.Net NuGet package using the Package Manager Console.
```
PM > Install-Package Mjml.Net
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md

Configure MJML rendering with MjmlOptions

main

You can customize the rendering behavior by providing an MjmlOptions instance to the Render method.

Name	Data Type	Default	Description
`Beautify`	`bool`	`true`	If `true`, the output HTML is beautified. Note: This impacts performance (slower).
`Breakpoint`	`string`	`480px`	The default breakpoint used to switch to mobile view.
`FileLoader`	`IFileLoader?`	`null`	A loader for `<mj-include path="..." type="...">` tags (e.g., `DiskFileLoader`, `InMemoryFileLoader`).
`Fonts`	`IReadOnlyDictionary<string, Font[]>`	`Preset`	A list of supported default fonts.
`ForceOWAQueries`	`bool`	`false`	If `true`, enables media queries for Outlook Web App (OWA).
`IdGenerator`	`IIdGenerator`	`Preset`	The generator used to create random values for attributes like `Ids`.
`KeepComments`	`bool`	`false`	If `true`, preserves HTML comments in the output.
`Lax`	`bool`	`false`	In lax mode, some XML errors are fixed. Warning: Only use when MJML is passed as a string; do not use in production as it can hurt performance.
`Minify`	`bool`	`false`	Minifies the HTML. (Deprecated with version 2.0.0)
`PostProcessors`	`IPostProcessor[]?`	`[]`	An array of post-processors to run on the HTML after rendering.
`Styles`	`Style[]?`	`[]`	A list of custom styles to apply.
`ValidatorFactory`	`IValidatorFactory?`	`null`	The current validator, which also defines the validation mode.
`XmlEntities`	`IReadOnlyDictionary<string, string>`	`Preset`	A list of supported XML entities. (Deprecated with version 1.16.0)

Handle non-encoded URLs and non-XML HTML tags (Pre-v2.0.0)
main
In versions prior to 2.0.0, the XmlReader parser may throw exceptions for non-encoded URLs or HTML tags that are not valid XML (such as  ).
Solutions:
1. For URLs: URL-encode all URLs in the template.
2. For HTML tags: Convert tags to XHTML format (e.g., use   or   instead of  ).
3. Global Fix: Enable lax mode in your configuration by setting options.Lax = true.
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Run BenchmarkDotNet profiler
main
To run the BenchmarkDotNet executable with the profiler enabled and a specific iteration count, use the -p and -i flags.
```
.
Mjml.Net.Benchmark.exe -p -i 100
```
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Supported MJML Components in MJML.NET
main
MJML.NET aims for 1-2-1 parity with the MJML 4 project. The following components are implemented, tested, and marked as 'Feature Complete':
Core Components
- mjml
- mj-head
- mj-body
- mj-include
Head Components
- mj-attributes
- mj-class
- mj-all
- mj-breakpoint
- mj-font
- mj-html-attributes
- mj-preview
- mj-style
- mj-title
Body Components
- mj-accordion
- mj-button
- mj-carousel
- mj-column
- mj-divider
- mj-group
- mj-hero
- mj-image
- mj-navbar
- mj-raw
- mj-section
- mj-social
- mj-spacer
- mj-table
- mj-text
- mj-wrapper
https://github.com/sebastianstehle/mjml-net/blob/main/README.md
Fix unknown HTML entities (Pre-v1.17.0)
main
In versions prior to 1.17.0, using HTML Character Entity Names (e.g., ©) may cause unhandled exceptions because the parser uses XmlReader.
Solution: Replace HTML Character Entity Names with their corresponding HTML Character Entity Numbers (e.g., ©).
Common conversions:
Entity Name Entity Number
   
< <
> >
& &
" "
' '
© ©
® ®
™ ™
https://github.com/sebastianstehle/mjml-net

Entity Name	Entity Number
` `	` `
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`
`'`	`'`
`©`	`©`
`®`	`®`
`™`	`™`

Entity Name	Entity Number
` `	` `
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`
`'`	`'`
`©`	`©`
`®`	`®`
`™`	`™`

MJML.NET

What's inside MJML.NET

Core Components

Head Components

Body Components

Entity Name	Entity Number
` `	` `
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`
`'`	`'`
`©`	`©`
`®`	`®`
`™`	`™`