### Set up MJML Development Environment Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Clone the MJML repository and install dependencies using Yarn to start development. This includes building the project. ```bash git clone https://github.com/mjmlio/mjml.git && cd mjml yarn yarn build ``` -------------------------------- ### Install mjml-preset-core Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-preset-core/README.md Install the mjml-preset-core package using npm. ```bash npm install --save mjml-preset-core ``` -------------------------------- ### Install MJML Locally Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Install MJML as a project dependency using npm. This is the recommended approach for local project usage. ```bash npm install mjml ``` -------------------------------- ### Run MJML from Local Installation Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Execute the MJML CLI from a local project installation. This command renders an MJML file to HTML. ```bash ./node_modules/.bin/mjml input.mjml ``` -------------------------------- ### Install MJML via NPM Source: https://github.com/mjmlio/mjml/blob/master/README.md Use this command to install the MJML package for Node.js or CLI usage. ```bash npm install mjml ``` -------------------------------- ### Use mjml-preset-core with mjml2html Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-preset-core/README.md Import and use mjml-preset-core with mjml2html to convert MJML code to HTML. Ensure mjml-core is also installed. ```javascript import mjml2html from 'mjml-core' import presetCore from 'mjml-preset-core' async function example() { const result = await mjml2html(`code`, { presets: [presetCore] }) console.log(result) } example() ``` -------------------------------- ### Install MJML and Community Components via npm Source: https://github.com/mjmlio/mjml/blob/master/doc/community-components.md These shell commands demonstrate how to install the MJML framework and a specific community component locally within your project directory using npm. This is the first step to using custom components. ```shell npm install mjml npm install {component-name} ``` -------------------------------- ### Install MJML Core Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/README.md Use npm to add the mjml-core package to your project dependencies. ```bash npm install --save mjml-core ``` -------------------------------- ### Allowlist Include Directories Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Explicitly allow additional root directories for MJML includes. This example allows includes from `../_common` and `../vendor` relative to the working directory. ```bash # Allow includes and declare two additional roots (JSON array) $> mjml template.mjml \ --config.filePath /project/templates/newsletter \ --config.allowIncludes true \ --config.includePath '["../_common","../vendor"]' ``` ```bash # Or provide absolute paths $> mjml template.mjml \ --config.filePath /project/templates/newsletter \ --config.allowIncludes true \ --config.includePath '["/project/templates/_common","/project/vendor"]' ``` -------------------------------- ### Adding Content at File Start with mj-raw Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-raw/README.md Place mj-raw outside of mj-body and mj-head, with the 'position="file-start"' attribute, to add content before the line. Minifier may join multiple lines into one. ```xml This will be added at the beginning of the file ``` -------------------------------- ### Change Juice Options Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Customize the behavior of the juice library used for inlining CSS. This example preserves important CSS declarations. ```bash $> mjml input.mjml --config.juiceOptions='{"preserveImportant": true}' ``` -------------------------------- ### Include MJML Header Source: https://github.com/mjmlio/mjml/blob/master/doc/components_2.md Example of an external MJML file to be included. Ensure includes are enabled in your MJML configuration. ```xml This is a header ``` -------------------------------- ### MJML Wrapper Example with Nested Sections Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-wrapper/README.md This example demonstrates how to use the mj-wrapper component to group two mj-section elements. It showcases shared border and padding on the wrapper, and individual styling for the sections within. The wrapper itself has a black border and padding, while the sections have top/bottom borders and internal padding. ```xml First line of text Second line of text ``` -------------------------------- ### Compile MJML to HTML in Node.js Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md This snippet shows how to use the mjml2html function to convert an MJML string into responsive HTML. It also demonstrates how to log the output and any potential errors. Ensure the 'mjml2html' package is installed. ```javascript import mjml2html from 'mjml' /* Compile an mjml string */ async function renderMjml() { const htmlOutput = await mjml2html( ` Hello World! `, options, ) /* Print the responsive HTML generated and MJML errors if any */ console.log(htmlOutput) } renderMjml() ``` -------------------------------- ### Basic MJML Structure Example Source: https://github.com/mjmlio/mjml/blob/master/doc/guide.md This snippet demonstrates the basic structure of an MJML document, including the main mjml, mj-body, mj-section, and mj-column tags. It also shows the usage of common components like mj-image, mj-divider, and mj-text, illustrating how to define content and apply basic styling. ```html Hello World ``` -------------------------------- ### Run MJML Locally with Community Components Source: https://github.com/mjmlio/mjml/blob/master/doc/community-components.md This command shows how to execute the MJML compiler locally from your terminal after installing MJML and community components. It processes an MJML file (e.g., index.mjml) and generates the corresponding HTML output. ```shell ./node_modules/.bin/mjml index.mjml ``` -------------------------------- ### MJML Image Component Attributes Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-carousel/README.md A reference guide for the attributes supported by the MJML image component. ```APIDOC ## MJML Image Component Attributes ### Description This component allows for the inclusion of images in MJML templates with various styling and accessibility options. ### Attributes - **alt** (string) - Optional - image description (default: '') - **border-radius** (string) - Optional - border radius of the main image - **css-class** (string) - Optional - class name, added to the root HTML element created - **href** (string) - Optional - link to redirect to on click, URL format - **rel** (string) - Optional - specify the rel attribute - **src** (string) - Optional - URL format - **target** (string) - Optional - link target on click (default: '_blank') - **tb-border** (string) - Optional - CSS border format - **tb-border-radius** (string) - Optional - border radius of the thumbnail - **thumbnails-src** (string) - Optional - specify a different thumbnail image in URL format - **title** (string) - Optional - tooltip & accessibility ``` -------------------------------- ### Override Base Path for MJ-Include Relative Paths Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Set a base path for resolving relative paths in MJML includes. This example ensures `` includes from `./my-partials/header.mjml`. ```bash $> mjml ./my-project/input.mjml --config.filePath ./my-partials/ ``` -------------------------------- ### Implement an interactive accordion in MJML Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-accordion/README.md This example demonstrates how to configure an mj-accordion using mj-attributes for styling and nesting mj-accordion-element components. It shows how to provide titles and text content that users can expand within an email. ```xml Why use an accordion? Because emails with a lot of content are most of the time a very bad experience on mobile, mj-accordion comes handy when you want to deliver a lot of information in a concise way. How it works Content is stacked into tabs and users can expand them at will. If responsive styles are not supported (mostly on desktop clients), tabs are then expanded and your content is readable at once. ``` -------------------------------- ### Basic MJML Structure with MJ-Body Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-body/README.md This is the starting point of your email. MJML automatically adds ARIA attributes for accessibility. The lang and dir attributes are also added here. ```xml ``` -------------------------------- ### Implement Social Media Icons with MJML Source: https://github.com/mjmlio/mjml/blob/master/doc/basic.md This code demonstrates the integration of social media icons in an MJML email using the `mj-social` and `mj-social-element` components. It shows a basic example of adding a Facebook share button within a single column layout. MJML provides built-in support for various social media platforms, and custom options are also available. ```html Share ``` -------------------------------- ### Define CSS styles with mj-style Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-head-style/README.md This example demonstrates how to use the mj-style component to define both inlined and head-level CSS. It also illustrates how to apply these styles to MJML body components using the css-class attribute. ```xml .blue-text div { color: blue !important; } .red-text div { color: red !important; text-decoration: underline !important; } I'm red and underlined I'm blue because of inline I'm green ``` -------------------------------- ### Define Manually Sized Columns in MJML Source: https://github.com/mjmlio/mjml/blob/master/doc/getting_started.md Shows how to explicitly control column width using the 'width' attribute on the mj-column tag. This allows for precise layout control using either pixel values or percentages. ```html ``` -------------------------------- ### Enable CSS Minification with Presets Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Enable CSS minification using the 'lite' preset with `minifyCss: "lite"`. The legacy `minifyCSS: true` also maps to the 'lite' preset. ```bash # lite preset mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCss": "lite"}' ``` ```bash # legacy equivalent (maps to lite) mjml input.mjml -o output.html --config.minify true --config.minifyOptions '{"minifyCSS": true}' ``` -------------------------------- ### Define Auto-Sized Columns in MJML Source: https://github.com/mjmlio/mjml/blob/master/doc/getting_started.md Demonstrates the default behavior where the MJML engine automatically divides the section width equally among the declared columns. This approach ensures responsive layout distribution without explicit width attributes. ```html ``` -------------------------------- ### Configure Include Paths via CLI Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Use the MJML CLI to enable includes and specify allowed directories for template inclusions. ```bash $> mjml template.mjml \ --config.filePath /project/templates/newsletter \ --config.allowIncludes true \ --config.includePath '["../_common","../vendor"]' ``` -------------------------------- ### Allow Includes for Local Development Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Enable MJML includes for local development. By default, includes are ignored for security reasons. ```bash $> mjml input.mjml --config.allowIncludes true ``` -------------------------------- ### Set Configuration File Path Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Specifies the base directory for resolving `mj-include` paths and scoping the include sandbox. This is particularly useful when using `--stdin` and no input file is present on disk. ```bash mjml [input] --config.filePath ``` -------------------------------- ### Include External CSS Files Source: https://github.com/mjmlio/mjml/blob/master/doc/components_2.md Shows how to include external CSS files, with options for standard inclusion or inlining. Use type="css" for CSS files. ```xml ``` -------------------------------- ### Watch for Changes Source: https://github.com/mjmlio/mjml/blob/master/README.md Run this command to automatically rebuild the package during development. ```bash yarn build:watch ``` -------------------------------- ### Include External HTML File Source: https://github.com/mjmlio/mjml/blob/master/doc/components_2.md Demonstrates including an external HTML file, which will be inserted similarly to an mj-raw tag. Use type="html" for HTML files. ```xml ``` -------------------------------- ### Preserve Specific Tags with Inline MJ-Style Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Preserve specific HTML tags when inlining CSS using ``. This example preserves custom tags like `<# myTag >`. ```bash $> mjml input.mjml --config.juicePreserveTags='{"myTag": { "start": "<#", "end": "

Easy and quick

Write less code, save time and code more efficiently with MJML’s semantic syntax.

Responsive

MJML is responsive by design on most-popular email clients, even Outlook.

 ``` -------------------------------- ### Compile MJML to HTML Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md This snippet demonstrates how to use the `mjml2html` function to convert an MJML string into responsive HTML. It also shows how to handle potential errors. ```APIDOC ## Compile MJML to HTML ### Description Converts an MJML string to HTML using the `mjml2html` function. Includes basic error handling and output logging. ### Method `mjml2html(mjmlString, options)` ### Parameters #### Request Body - **mjmlString** (string) - Required - The MJML markup to convert. - **options** (object) - Optional - Configuration options for the conversion process. ### Request Example ```json { "mjmlString": "...", "options": { "beautify": true } } ``` ### Response #### Success Response (200) - **html** (string) - The generated HTML output. - **errors** (array) - An array of MJML errors, if any. #### Response Example ```json { "html": "...", "errors": [] } ``` ``` -------------------------------- ### Compile MJML file via CLI Source: https://github.com/mjmlio/mjml/blob/master/README.md Basic command to compile an MJML file and save the output to a specified HTML file. ```bash mjml input.mjml -o output.html ``` -------------------------------- ### Basic MJML Structure with Columns Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-column/README.md Demonstrates the basic structure of an MJML document using two columns within a section. Ensure columns are direct children of mj-section. ```xml ``` -------------------------------- ### Include MJML File in Main Template Source: https://github.com/mjmlio/mjml/blob/master/doc/components_2.md Demonstrates how to include an external MJML file within the main MJML structure. Includes are disabled by default and must be explicitly enabled. ```xml ``` -------------------------------- ### Render MJML to Stdout Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Render an MJML file and redirect the resulting HTML output to standard output. ```bash mjml -s input.mjml ``` ```bash mjml --stdout input.mjml ``` -------------------------------- ### Set Template Syntax Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md Sets custom delimiters for template syntax, such as `{{ }}` or `[[ ]]`. Provide a JSON array of objects, where each object specifies the `prefix` and `suffix` for the delimiters. Defaults to `[{"prefix":"{{","suffix":"}}"},{"prefix":"[[","suffix":"]]"}]`. ```bash mjml [input] --config.templateSyntax ``` -------------------------------- ### Compile with Single Include Directory Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Use the MJML API to compile a template with includes enabled and a single directory specified for allowed paths. ```javascript import mjml2html from 'mjml' async function compileOne(source) { const { html, errors } = await mjml2html(source, { ignoreIncludes: false, filePath: '/project/templates/campaignA/email1.mjml', includePath: '/project/templates/_common', }) } ``` -------------------------------- ### Add MJML to PATH Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Add the local MJML binary directory to your system's PATH environment variable for easier access. ```bash export PATH="$PATH:./node_modules/.bin" ``` -------------------------------- ### Minify and Beautify Output HTML Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Configure MJML to minify and beautify the output HTML. These are the default settings. ```bash $> mjml input.mjml --config.beautify true --config.minify false ``` -------------------------------- ### Allow Mixed Template Syntaxes Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Enable the use of mixed template syntaxes (e.g., block and CSS tokens) within the same MJML document. Requires enabling style sanitization and HTML minification. ```bash $> mjml input.mjml --config.sanitizeStyles true --config.minify true --config.allowMixedSyntax true ``` -------------------------------- ### Enable MJ-Include Processing Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Enables the processing of `mj-include` tags within MJML files, allowing for modular template design. Set to `true` to activate, `false` to disable. ```bash mjml [input] --config.allowIncludes ``` -------------------------------- ### Add Include Paths Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Adds allowlisted root directories for `mj-include` processing. Paths can be specified as a single string or a JSON array. Relative paths are resolved from the CLI working directory. ```bash mjml [input] --config.includePath ``` -------------------------------- ### Custom Social Element Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-social/README.md Demonstrates how to use custom social elements when a network is not supported by default. ```APIDOC ## Custom Social Element ### Description Allows for the inclusion of social networks not natively supported by MJML by providing custom icons and links. ### Usage You can add any unsupported network by providing the necessary attributes: ```xml Optional label ``` ### Notes - The `href` attribute is mandatory for custom elements that link to a URL. - `background-color` and `src` (path to your icon) are used to style and display the custom social icon. - You can include an optional label that will appear next to the icon. ### Simple List of Images/Texts If you do not provide an `href` attribute, `mj-social` will render a simple list of inlined images and texts without any linking functionality. ``` -------------------------------- ### MJML Config File Path Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md Specifies the path to a `.mjmlconfig` file. This file can be used to define custom components and configurations. If not specified, it defaults to the current working directory. ```bash mjml [input] --config.mjmlConfigPath ``` -------------------------------- ### Output to Stdout Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md This command compiles an MJML file and outputs the resulting HTML directly to standard output (stdout). Useful for piping the output to other commands or processes. ```bash mjml [input] -s ``` -------------------------------- ### Minify Options Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md Specifies options for the HTML minifier. Use `minifyCss` to control CSS minification. Refer to the MJML CLI documentation for a full list of available options. ```bash mjml [input] --config.minifyOptions ``` -------------------------------- ### Preserve CSS Tokens with MJML CLI Source: https://github.com/mjmlio/mjml/blob/master/doc/tooling.md Use this CLI command to minify MJML output while preserving CSS template tokens. Ensure `sanitizeStyles` and `minify` are enabled. ```bash mjml input.mjml -o out.html --config.sanitizeStyles true --config.minify true ``` -------------------------------- ### Allow Mixed Syntax with MJML CLI Source: https://github.com/mjmlio/mjml/blob/master/doc/tooling.md This CLI command enables the mixing of block and CSS tokens within the same MJML document, alongside CSS token preservation and minification. ```bash mjml input.mjml -o out.html --config.sanitizeStyles true --config.minify true --config.allowMixedSyntax true ``` -------------------------------- ### MJML Conversion Options Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml/README.md Details the available options that can be passed to the `mjml2html` function to customize the conversion process. ```APIDOC ## MJML Conversion Options ### Description These options can be passed as an object to the `mjml2html` function to customize the MJML to HTML conversion. ### Options Table | Option Name | Type | Description | |------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | allowMixedSyntax | boolean | Allows mixed block/value/property template syntaxes during CSS sanitization. | | beautify | boolean | Option to beautify the HTML output. | | filePath | string | Path of file, used for relative paths in `mj-include` instances. | | fonts | object | Default fonts imported in the HTML rendered by MJML. | | ignoreIncludes | boolean | Option to ignore `mj-include` instances. | | includePath | string or string[]| Additional allowlisted include roots, used when `ignoreIncludes` is `false`. | | juicePreserveTags| object | Preserve some tags when inlining CSS. | | keepComments | boolean | Option to keep comments in the HTML output. | | minify | boolean | Option to minify the HTML output. | | minifyOptions | object | Options for htmlnano minification (including `minifyCss`). | | mjmlConfigPath | string | The path or directory of the `.mjmlconfig` file (for custom components use). | | preprocessors | array of functions| Preprocessors applied to the xml before parsing. Input must be xml, not json. Functions must be `(xml: string) => string`. | ``` -------------------------------- ### Compile MJML to HTML in Browser Source: https://github.com/mjmlio/mjml/blob/master/README.md Use `mjml-browser` to compile MJML strings to HTML directly in the browser. The `then` function handles the asynchronous output, providing the HTML and any MJML errors. ```javascript var mjml2html = require('mjml-browser') /* Compile a mjml string */ mjml2html(` Hello World! `, options).then(function (htmlOutput) { /* Print the responsive HTML generated and MJML errors if any */ console.log(htmlOutput) }) ``` -------------------------------- ### Compile MJML to HTML in Node.js Source: https://github.com/mjmlio/mjml/blob/master/README.md Use the `mjml2html` function to convert an MJML string into responsive HTML. Ensure the MJML library is imported. The function returns an object containing the HTML output and any MJML errors. ```javascript import mjml2html from 'mjml' /* Compile an mjml string */ async function renderMjml() { const htmlOutput = await mjml2html(` Hello World! `, options) /* Print the responsive HTML generated and MJML errors if any */ console.log(htmlOutput) } renderMjml() ``` -------------------------------- ### MJML Two-Column Layout Source: https://github.com/mjmlio/mjml/blob/master/doc/basic.md A side-by-side layout using two mj-column elements, one for an image and one for text content, demonstrating self-closing tag syntax. ```html Find amazing places Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin rutrum enim eget magna efficitur, eu semper augue semper. Aliquam erat volutpat. Cras id dui lectus. Vestibulum sed finibus lectus. ``` -------------------------------- ### Watch MJML File for Changes Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Enable watch mode to automatically re-render an MJML file whenever it is saved. Useful for live-coding scenarios. ```bash mjml -w input.mjml ``` ```bash mjml --watch input.mjml ``` -------------------------------- ### Change Minify Options Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/README.md Customize minify options for the output HTML using a JSON string. This allows fine-grained control over HTML minification. ```bash $> mjml input.mjml --config.minifyOptions='{"minifyCss": true, "removeEmptyAttributes": false}' ``` -------------------------------- ### Compile MJML to HTML File Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Compiles an MJML input file and saves the generated HTML to a specified output file. This is the most common usage for generating static HTML emails. ```bash mjml input.mjml -o output.html ``` -------------------------------- ### Render MJML to HTML Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/README.md Import the mjml2html function to convert MJML strings into HTML output. ```javascript import mjml2html from 'mjml' async function example() { const result = await mjml2html(`code`) console.log(result) } example() ``` -------------------------------- ### Configure MJML Packages with .mjmlconfig Source: https://github.com/mjmlio/mjml/blob/master/doc/community-components.md This JSON configuration file specifies the paths to community components that MJML should recognize and load. It's essential for integrating custom or third-party MJML components into your project. ```json { "packages": ["component-name/path-to-js-file"] } ``` -------------------------------- ### Compile MJML to HTML in Browser Source: https://github.com/mjmlio/mjml/blob/master/packages/mjml-browser/README.md Demonstrates how to import the mjml-browser package and invoke the mjml2html function. This function accepts an MJML string and an options object to return the compiled HTML output. ```javascript var mjml2html = require('mjml-browser') var result = mjml2html(mjml, options) ``` -------------------------------- ### Allow Mixed Syntax Source: https://github.com/mjmlio/mjml/blob/master/doc/install.md Permits the mixing of block tokens (e.g., `{%...%}`) with CSS tokens (e.g., `color: {{...}}`) in the same MJML document. Set to `true` to enable this flexibility. ```bash mjml [input] --config.allowMixedSyntax ``` -------------------------------- ### MJML Image Header with Button Source: https://github.com/mjmlio/mjml/blob/master/doc/basic.md A section featuring a background image, a slogan text, and a call-to-action button, utilizing background-url and column width constraints. ```html Slogan here Promotion ```