mjml README

The project's README from github.com/mjmlio/mjml. As one markdown file: README.md.

Developed by

github actions

| Introduction | Installation | Usage |

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.

Installation

You can install MJML with NPM to use it with NodeJS or the Command Line Interface. If you're not sure what those are, head over to Usage for other ways to use MJML.

npm install mjml

Development

To work on MJML, make changes and create pull requests, download and install yarn for easy development.

git clone https://github.com/mjmlio/mjml.git && cd mjml
yarn
yarn build

You can also run yarn build:watch to rebuild the package as you code.

Usage

Online

Don't want to install anything? Use the free online editor!

try it live

Applications and plugins

MJML comes with tools and plugins, check out:

For more tools, check the Community page.

Command line interface

Compiles the file and outputs the HTML generated in output.html

mjml input.mjml -o output.html

You can pass optional arguments to the CLI and combine them.

argument description default value
mjml [input] -o [output] Writes the output to [output]
mjml [input] -s Writes the output to stdout
mjml [input] -s --noStdoutFileComment Writes the output to stdout without file comment in the first line
mjml -w [input] Watches the changes made to [input] (file or folder)
mjml [input] --config.allowIncludes Enables mj-include processing (true or false) false
mjml [input] --config.allowMixedSyntax Allows mixing block and CSS variable syntax when sanitizeStyles is enabled (true or false) false
mjml [input] --config.beautify Beautifies the output (true or false) true
mjml [input] --config.includePath Adds allowlisted include root(s), as a string path or JSON array of paths
mjml [input] --config.minify Minifies the output (true or false) false
mjml [input] --config.minifyOptions Options for HTML minifier, use minifyCss to control CSS minification See mjml-cli documentation
mjml [input] --config.juicePreserveTags Preserve some tags when inlining CSS See mjml-cli documentation
mjml [input] --config.mjmlConfigPath Path to .mjmlconfig file for custom components current working directory
mjml [input] --config.sanitizeStyles Sanitizes template variables inside CSS before minification (true or false) false
mjml [input] --config.useMjmlConfigOptions Allows to use the options attribute from .mjmlconfig file false
mjml [input] --config.templateSyntax Sets custom template delimiters as JSON array ([{"prefix":"{{","suffix":"}}"}]) [{"prefix":"{{","suffix":"}}"},{"prefix":"[[","suffix":"]]"}]

See mjml-cli documentation for more information about config options.

Inside Node.js

import mjml2html from 'mjml'

/*
  Compile an mjml string
*/
async function renderMjml() {
  const htmlOutput = await mjml2html(`
    <mjml>
      <mj-body>
        <mj-section>
          <mj-column>
            <mj-text>
              Hello World!
            </mj-text>
          </mj-column>
        </mj-section>
      </mj-body>
    </mjml>
  `, options)

  /*
    Print the responsive HTML generated and MJML errors if any
  */
  console.log(htmlOutput)
}

renderMjml()

You can pass optional options as an object to the mjml2html function:

option unit description default value
allowMixedSyntax boolean Allows mixed block/value/property template syntaxes during CSS sanitization false
beautify boolean Option to beautify the HTML output false
filePath string Path of file, used for relative paths in mj-include instances .
fonts object Default fonts imported in the HTML rendered by MJML See in index.js
ignoreIncludes boolean Option to ignore mj-include instances true
includePath string or string[] Additional allowlisted include root(s), used when ignoreIncludes is false
juicePreserveTags object Preserve some tags when inlining CSS, see documentation for more info
keepComments boolean Option to keep comments in the HTML output true
minify boolean Option to minify the HTML output false
minifyOptions object Options for htmlnano minification (including minifyCss), see documentation for more info
mjmlConfigPath string The path or directory of the .mjmlconfig file (for custom components use) process.cwd()
preprocessors array of functions Preprocessors applied to the xml before parsing. Input must be xml, not json. Functions must be (xml: string) => string []
sanitizeStyles boolean Sanitizes template variables in CSS before minification false
templateSyntax array of objects Custom template delimiters used by sanitization ([{ prefix, suffix }]) [{"prefix":"{{","suffix":"}}"},{"prefix":"[[","suffix":"]]"}]
useMjmlConfigOptions boolean Allows to use the options attribute from .mjmlconfig file false
validationLevel string Available values for the validator: strict, soft, skip soft.

Client-side (in browser)

var mjml2html = require('mjml-browser')

/*
  Compile a mjml string
*/
mjml2html(`
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text>
            Hello World!
          </mj-text>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
`, options).then(function (htmlOutput) {
  /*
    Print the responsive HTML generated and MJML errors if any
  */
  console.log(htmlOutput)
})

API

A free-to-use MJML API is available to make it easy to integrate MJML in your application. Head over here to learn more about the API.

MJML Slack

MJML wouldn't be as cool without its amazing community. Head over the Community Slack to meet fellow MJML'ers.

mjml (mjmlio/mjml)

Searching Database…

18.3K ·GitHub
Mjml
What is this?MJML is a markup language created by Mailjet that lets you write responsive HTML emails using simple semantic tags instead of hand-coding table-based HTML and inline CSS.
Is it a framework, a library, or a CLI tool?It's all three: a markup language with an open-source compiler engine, usable as a Node.js library, a command-line interface, or through online/editor tools.
How do I start using it?Install it via NPM for Node.js or CLI use, or skip installing anything and use the free online editor.
What do I need before writing MJML templates?You just need Node.js/NPM to install the package; for contributing to MJML itself you'd also need Yarn.
Does the CLI require any extra flags to handle things like includes or style sanitization?Yes, several features are off by default: mj-include processing, mixed template syntax, and style sanitization all need explicit flags like --config.allowIncludes or --config.sanitizeStyles.
How do I actually run the compiler on a file?Use the mjml command, e.g. 'mjml [input] -o [output]' to write HTML to a file, or '-s' to print it to stdout.
Can I use MJML without installing anything locally?Yes, there's a free online editor and a free-to-use MJML API for integrating MJML compilation into your own application without local setup.
Are there editor plugins for writing MJML?Yes, there's an official Visual Studio Code extension (bundled or from the Marketplace/Open VSX) and a Sublime Text plugin.
Can I customize the output HTML, like minifying or beautifying it?Yes, the CLI and Node API support options like minify, beautify, and minifyOptions to control the generated HTML's formatting and size.
What are similar projects?react-email, tools, marked, git-history, lollipop-css, marp, graphiql, buildawesome
Which topics is it in?responsive, vscode-extension, vscode, email, command-line, html, markdown, npm, frontend, nodejs, javascript, cli
Creator
mjmlio
Size
12.7 MB
Stars
18.3K
Updated
CommitSep 10Releasev5.4.1Sep 10
Age
10y
Commits · 90 Days