MRML Documentation

To use MRML in your Rust project, add it to your Cargo.toml dependencies. It is recommended to also include serde with the derive feature for compatibility with data structures.

[dependencies]
mrml = { version = "*" }
serde = { version = "1", features = ["derive"] }

Once the mrml-bench image is built, you can run benchmarks against specific .mjml files using docker run. The --rm flag ensures the container is removed after the benchmark completes.

Example files provided in the benchmark suite include /air-astana.mjml and /amario.mjml.

docker run --rm mrml-bench /air-astana.mjml
docker run --rm mrml-bench /amario.mjml

You can parse an MJML string into a document tree and then render it to HTML using mrml::parse and mrml::prelude::render::RenderOptions.

Note: This requires the parse feature to be enabled in your Cargo.toml.

let root = mrml::parse("<mjml><mj-body></mj-body></mjml>").expect("parse template");
let opts = mrml::prelude::render::RenderOptions::default();
match root.element.render(&opts) {
    Ok(content) => println!("{}", content),
    Err(_) => println!("couldn't render mjml template"),
};

The mrml-cli provides several commands to work with MJML templates and JSON representations.

• Validate: Check an MJML template for correctness.
• Render: Convert an MJML template into its output format.
• format-json: Convert an MJML template into a formatted JSON structure. Use the --pretty flag for human-readable output.
• format-mjml: Convert a JSON structure back into a formatted MJML template. Use the --pretty flag for human-readable output.

# Validate an MJML template
mrml-cli path/to/template.mjml validate

# Render an MJML template
mrml-cli path/to/template.mjml render

# Convert MJML to pretty-printed JSON
mrml-cli path/to/template.mjml format-json --pretty

# Convert JSON to pretty-printed MJML
mrml-cli path/to/template.json format-mjml --pretty

To use MRML in a web browser environment, import the Engine class from the mrml package. Instantiate the Engine and use the toHtml method to convert MRML markup strings into HTML.

import { Engine } from "mrml";

const engine = new Engine();
const result = engine.toHtml("<mjml><mj-body>Hello World</mj-body></mjml>");

To use MRML in a Node.js environment, require the Engine class from the mrml/node/mrml entry point. Instantiate the Engine and use the toHtml method to convert MRML markup strings into HTML.

const { Engine } = require("mrml/node/mrml");

const engine = new Engine();
const result = engine.toHtml("<mjml><mj-body>Hello World</mj-body></mjml>");

To use the mrml-wasm package within the examples/demo project, you must first build the WASM package and link it locally using yarn link. This allows the demo to consume the local version of the library instead of a published version.

Follow these steps:

1. Navigate to the packages/mrml-wasm directory.
2. Run the build script to compile the WASM components.
3. Use yarn link inside the package directory to register it locally.
4. Navigate back to examples/demo and run yarn link mrml to connect the demo to your local build.

# go to packages/mrml-wasm
bash build.sh
cd pkg
yarn link

# go back to examples/demo
yarn link mrml

You can install the mrml-cli tool using cargo. It is recommended to use the --locked flag to ensure dependency versions match the repository's lockfile.

cargo install --locked mrml-cli

To build the Docker image used for benchmarking MRML, run the following command from the repository root. This uses the Dockerfile located in the benchmarks/ directory and tags the image as mrml-bench.

docker build -f benchmarks/Dockerfile -t mrml-bench .

The mrml-cli is a command-line tool used to format, render, and validate MJML templates. It supports both .mjml files and .json representations of MJML. You can provide an input file as a positional argument or pipe content via stdin.

mrml-cli <input_file> <subcommand> [options]
# Or via stdin
cat template.mjml | mrml-cli <subcommand>

MRML is available on PyPI. You can use mrml.to_html() to convert MJML strings to HTML. You can also provide ParserOptions to handle includes via a memory_loader.

import mrml

# without options
result = mrml.to_html("<mjml></mjml>")
assert result.content.startswith("<!doctype html>")

# with options
parser_options = mrml.ParserOptions(include_loader = mrml.memory_loader({
    'hello-world.mjml': '<mj-text>Hello World!</mj-text>',
}))
result = mrml.to_html("<mjml><mj-body><mj-include path=\"hello-world.mjml\" /></mj-body></mjml>", parser_options = parser_options)
assert result.content.startswith("<!doctype html>")

To handle includes (e.g., <mj-include path="..." />), you must provide mrml.ParserOptions containing a loader. You can use mrml.memory_loader() to define a virtual file system mapping file paths to MJML content strings.

import mrml

# with options
parser_options = mrml.ParserOptions(include_loader = mrml.memory_loader({
    'hello-world.mjml': '<mj-text>Hello World!</mj-text>',
}))
result = mrml.to_html("<mjml><mj-body><mj-include path=\"hello-world.mjml\" /></mj-body></mjml>", parser_options = parser_options)
assert result.content.startswith("<!doctype html>")