framix-team/skill-email-html-mjml / email-html-mjml
email-html-mjml
VerifiedResponsive HTML email template generation using MJML 5.x framework. Use when the user asks to create, generate, design, or build an email template — including welcome emails, promotional blasts, transactional templates, newsletters, or any responsive email. Also use when the user asks to compile MJML to HTML, work with or edit existing MJML templates or `.mjml` files, or troubleshoot email rendering issues across clients.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 10.6 KB |
| assets/examples/basic-layout.mjml | other | 3.7 KB |
| assets/examples/newsletter.mjml | other | 5.0 KB |
| assets/examples/order-confirmation.mjml | other | 4.1 KB |
| assets/examples/partials/footer.mjml | other | 742 B |
| assets/examples/promo-sale.mjml | other | 5.6 KB |
| compilation.md | markdown | 5.2 KB |
| components/advanced.md | markdown | 6.0 KB |
| components/content.md | markdown | 5.1 KB |
| components/head.md | markdown | 3.2 KB |
| components/interactive.md | markdown | 8.0 KB |
| components/layout.md | markdown | 4.8 KB |
| mjml-reference.md | markdown | 8.5 KB |
mjml-reference.md
View on GitHub# MJML General Reference
Non-component knowledge from the MJML documentation — architecture, behaviors, gotchas, and validation.
---
## mj-body Automatic ARIA Injection
MJML automatically wraps email body content in a `<div>` with the following accessibility attributes:
```html
<div role="article" aria-roledescription="email" aria-label="[value from mj-title]" lang="[from mjml tag]" dir="[from mjml tag]">
```
This means:
- Always set `<mj-title>` — it populates `aria-label` on the wrapper div, used by screen readers to identify the email
- Always set `lang` on the root `<mjml>` tag — it flows through to this div
---
## Ending Tags
The following components are **ending tags** — their content is raw HTML/text, NOT processed by the MJML engine. You cannot nest other MJML components inside them.
- `mj-text`
- `mj-button`
- `mj-table`
- `mj-raw`
- `mj-accordion-title`
- `mj-accordion-text`
- `mj-navbar-link`
- `mj-social-element`
**Implications:**
- You can use any HTML inside these (`<strong>`, `<a>`, `<span>`, etc.)
- Characters `<` and `>` used as literal text should be escaped as `<` and `>`
- **MJML 5 relaxed this.** A `<` followed by a space is now fine: `Price < 100 dollars` compiles and survives intact under `minify`. In MJML 4 the same input was a hard `Parse Error`. The `htmlnano` swap fixed it
- **But a *tag-like* `<` still breaks — silently.** `{{#if a<b}}yes{{/if}}` (a `<` immediately followed by a letter) compiles at exit `0` and emits mangled output: `{{#if a<b}}yes{{ if}}< div> </b}}yes{{>`. No error, no warning. Never treat exit `0` as proof here
- The fix is `<!-- htmlmin:ignore -->` around the tag, which preserves it byte-exact (markers must come in pairs and are stripped from the output). **Do not** substitute `<` for a template tag: the entity survives literally into the sent HTML (`{{#if a<b}}`), so the ESP never receives a `<` and the condition never evaluates
- `mj-html-attributes` and inline `mj-style` require re-parsing — can conflict with ending tag content
---
## Validation Levels
MJML validates component nesting and attributes. Three levels:
| Level | Behavior |
|-------|----------|
| `soft` (default) | Logs warnings, renders anyway |
| `strict` | Throws error and stops rendering on any syntax mistake |
| `skip` | No validation, renders as-is |
**CLI usage:**
```bash
# Validate without rendering
npx mjml --validate template.mjml
# Set validation level
npx mjml template.mjml --config.validationLevel=strict
npx mjml template.mjml --config.validationLevel=skip
```
**Recommended**: Use `strict` during development to catch nesting errors early.
---
## Hybrid Fluid Design — How Widths Work
MJML uses a "hybrid" or "spongy" approach:
- **Modern clients** (Apple Mail, Gmail app): fluid percentage widths
- **Outlook**: fixed-width ghost tables (VML-based)
Column widths are auto-calculated from the section width (default 600px):
- 1 column = 100% (600px)
- 2 columns = 50% each (300px each)
- 3 columns = 33.33% each (200px each)
- Set explicit `width` on `mj-column` to override (must sum to 100% or 600px)
Columns stack vertically on mobile. Use `mj-group` to prevent stacking.
---
## What MJML Actually Generates
MJML compiles semantic tags into complex nested tables. Example — `mj-button` becomes:
```html
<table cellpadding="0" cellspacing="0" style="border:none;border-radius:3px;" align="center">
<tbody><tr>
<td style="background-color:#414141;border-radius:3px;color:#ffffff;cursor:auto;" align="center" valign="middle" bgcolor="#414141">
<a class="mj-content" href="#"
style="display:inline-block;text-decoration:none;background-color:#414141;border:1px solid #414141;border-radius:3px;color:#ffffff;font-size:13px;font-weight:bold;padding:15px 30px;"
target="_blank">
Hello There!
</a>
</td>
</tr></tbody>
</table>
```
This is why hand-coding email HTML is error-prone — MJML handles this complexity automatically.
---
## css-class and container-background-color
Available on **all body components**:
- **`css-class`**: Adds a class to the root HTML element generated by that component. Used to target with `mj-style` or `mj-html-attributes`. Note: the class lands on an outer element (usually `<td>`), not necessarily the visible content. Check compiled HTML to know which element gets the class.
- **`container-background-color`**: Sets the background color of the cell wrapping a content component inside a column. Different from the column's `background-color` — affects the per-component cell. **Exception (MJML 5): `mj-hero` no longer accepts it** — it was valid in v4 and is now `Attribute container-background-color is illegal`, a hard exit-1 failure under `--config.validationLevel=strict`.
```xml
<!-- container-background-color creates a highlight behind just this text block -->
<mj-text container-background-color="#fff9e6" padding="16px">
Important notice
</mj-text>
```
---
## mj-include File Types
| type attribute | Effect |
|---------------|--------|
| (omitted) | Treats file as `.mjml` — parsed and merged |
| `type="css"` | Inserted as `mj-style` |
| `type="css" css-inline="inline"` | Inserted as `mj-style inline="inline"` (Juice-inlined) |
| `type="html"` | Inserted as `mj-raw` — no parsing |
Base path override: `--config.filePath ./partials/` — allows includes to resolve from a fixed directory regardless of where the compiled file lives.
**MJML 5**: includes are disabled unless explicitly enabled (`--config.allowIncludes true` CLI / `ignoreIncludes: false` Node API), and resolve only from the source file's directory plus any `--config.includePath` allowlist. See `components/advanced.md` for full detail.
---
## Preprocessors (.mjmlconfig.js)
JavaScript functions that receive raw MJML XML as a string **before parsing**. Useful for integrating templating engines (Handlebars, Liquid) at preview/dev time.
```js
// .mjmlconfig.js
module.exports = {
preprocessors: [
(xml) => xml.replace(/\{\{firstName\}\}/g, 'Preview Name')
]
}
```
Production: leave template tags in place (e.g. `{{firstName}}`), let your ESP (SendGrid, AWS SES) inject values. Use `<mj-raw>` to protect template syntax from the MJML parser.
---
## Node.js API (if not using the CLI)
This skill compiles via `npx mjml` (see `compilation.md`), but if the user wants to call MJML from a Node script (e.g. inside an ESP-sending pipeline), note that **`mjml2html` is asynchronous in MJML 5** — it returns a `Promise`, not a synchronous result as in MJML 4.
```js
import mjml2html from 'mjml'
const { html, errors } = await mjml2html(mjmlSource, {
validationLevel: 'strict',
minify: true,
ignoreIncludes: false, // only if the template uses mj-include
includePath: ['./partials'],
})
```
Key options mirror the CLI flags: `validationLevel`, `minify`, `minifyOptions`, `filePath`, `includePath`, `ignoreIncludes`, `allowMixedSyntax`, `sanitizeStyles`, `templateSyntax`, `beautify`.
---
## MJML 5 Output Differences
Two v5 changes affect the compiled HTML itself, independent of the template you write:
- **Minifier swap** — `--config.minify=true` now runs `htmlnano` + `cssnano` instead of `html-minifier`. CSS is minified more (total output is smaller than v4), but **HTML whitespace is minified less**: `htmlnano`'s `collapseWhitespace` collapses inter-tag runs to a single space where `html-minifier` removed them entirely. Any snapshot test or raw-HTML diff against v4 output will report changes. Pass `--config.minifyOptions '{"collapseWhitespace":"all"}'` to restore v4 behavior — the JSON-string form is required, `--config.minifyOptions.collapseWhitespace=all` fails to parse. (`cssnano` uses the `lite` preset by default.)
- **`<body>` is generated by `mj-body`** rather than a global skeleton. Notably, `css-class` on `mj-body` now lands on the `<body>` tag itself — in v4 it landed on the child `<div>`. External CSS or ESP tooling that targeted that class by position may no longer match.
Both are output-shape changes only — no template edits are required.
---
## Gmail 102KB Clip
Gmail clips emails exceeding **102KB**. The entire bottom of the email is hidden with a "View entire message" link.
**Prevention**: Always compile with minification:
```bash
npx mjml template.mjml -o output.html --config.minify=true
```
In MJML 4 minification also stripped whitespace between `inline-block` columns. **It no longer does** — see MJML 5 Output Differences above. Stacking is prevented by the `font-size:0px` MJML emits on the parent `<td>`; add `--config.minifyOptions '{"collapseWhitespace":"all"}'` if you want the v4 stripping back.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |