email-html-mjml

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

email-html-mjml — Responsive Email Developer

email-html-mjml — 响应式邮件开发工具

Generate valid, cross-client MJML 4.x templates and compile them to production-ready HTML. The primary goal is compatibility: Outlook (2013–365), Gmail (web/app), Apple Mail, and major mobile clients. Every output must be compilable with

--config.validationLevel=strict

and survive Gmail's 102KB clip limit.

生成符合规范、跨客户端兼容的MJML 4.x模板，并将其编译为可用于生产环境的HTML。核心目标是兼容性：支持Outlook（2013–365）、Gmail（网页版/应用版）、Apple Mail以及主流移动客户端。所有输出内容必须能够通过

--config.validationLevel=strict

编译，且不超过Gmail的102KB内容截断限制。

Workflow

工作流程

Gather requirements — Infer email type, brand colors, and content from the user's message and conversation context. Ask only for what is genuinely missing and blocking progress (e.g., no colors provided and the layout has branded sections). Never front-load a questionnaire.
Plan layout — Decide and announce the structure before writing code (single-column, 2-col grid, hero + content, etc.)
Load component references — Read the relevant file(s) from the Component Index below before writing any MJML
Generate MJML — Write complete, valid MJML starting from
```
<mjml>
```
with a full
```
<mj-head>
```

Compile — Follow

compilation.md

. Run

npx mjml

with

--config.minify=true

Deliver both files — Always output
```
.mjml
```
source AND compiled
```
.html
```

收集需求 — 从用户的消息和对话语境中推断邮件类型、品牌颜色和内容。仅询问真正缺失且会阻碍进度的信息（例如，未提供颜色但布局包含品牌相关板块）。切勿一开始就抛出一堆问题。
规划布局 — 在编写代码前确定并告知结构（单栏、双栏网格、首屏横幅+内容等）
加载组件参考 — 在编写任何MJML代码前，先阅读下方组件索引中的相关文件
生成MJML — 编写完整、合规的MJML代码，从
```
<mjml>
```
标签开始，包含完整的
```
<mj-head>
```
编译 — 遵循
```
compilation.md
```
的要求。使用
```
npx mjml
```
命令并添加
```
--config.minify=true
```
参数
交付两个文件 — 始终输出
```
.mjml
```
源文件和编译后的
```
.html
```
文件

9 Engineering Rules

9条工程规则

Structural Integrity — All visual content MUST be in
```
<mj-column>
```
inside
```
<mj-section>
```
. Sections cannot be nested.
Responsive Defaults — Assume 600px width. Use
```
<mj-group>
```
to prevent mobile stacking for side-by-side elements (social bars, logo rows).
Outlook Compatibility — Use
```
<mj-font>
```
for web fonts (prevents Times New Roman fallback). Always provide a fallback stack (Arial, sans-serif). For
```
<mj-section>
```
background images, always set both
```
background-size
```
and a fallback
```
background-color
```
.
Gmail Optimization — Use
```
inline="inline"
```
on
```
<mj-style>
```
for custom CSS. Prefer component attributes (
```
color
```
,
```
font-size
```
) over CSS classes for critical styles.
Dark Mode — Include dark mode support when explicitly requested or when the email has a light background that would cause harsh forced-inversion. See the Dark Mode Pattern below.
Accessibility — Every
```
<mj-image>
```
MUST have
```
alt
```
. Always set
```
<mj-title>
```
(populates
```
aria-label
```
). Maintain WCAG 2.1 AA 4.5:1 contrast. For heading roles, use
```
mj-html-attributes
```
— direct
```
role
```
/
```
aria-level
```
attributes on
```
mj-text
```
are illegal under strict validation (see Accessibility Checklist below).
Styling Efficiency — Use
```
<mj-attributes>
```
with
```
<mj-all>
```
, component defaults, and
```
<mj-class>
```
to eliminate repetitive inline styles.
Hero Sections — Use
```
<mj-hero>
```
for full-bleed hero banners; it falls back to a regular section in unsupported clients. Avoid
```
<mj-accordion>
```
and
```
<mj-carousel>
```
— client support is too poor to be useful.
Templating Support — Wrap dynamic tags (Handlebars/Liquid) in
```
<mj-raw>
```
to protect them from the MJML parser.

结构完整性 — 所有可视化内容必须放在
```
<mj-section>
```
内的
```
<mj-column>
```
中。Section不能嵌套。
响应式默认设置 — 默认宽度设为600px。使用
```
<mj-group>
```
防止移动端的并排元素堆叠（如社交栏、Logo行）。
Outlook兼容性 — 使用
```
<mj-font>
```
引入网页字体（避免回退到Times New Roman）。始终提供备选字体栈（Arial, sans-serif）。对于
```
<mj-section>
```
的背景图片，始终同时设置
```
background-size
```
和备选
```
background-color
```
。
Gmail优化 — 在
```
<mj-style>
```
上使用
```
inline="inline"
```
来处理自定义CSS。优先使用组件属性（
```
color
```
、
```
font-size
```
）而非CSS类来设置关键样式。
深色模式 — 当用户明确要求，或邮件为浅色背景可能导致强制反转效果过于刺眼时，需支持深色模式。请参考下方的深色模式方案。
可访问性 — 每个
```
<mj-image>
```
必须设置
```
alt
```
属性。始终设置
```
<mj-title>
```
（用于填充
```
aria-label
```
）。保持WCAG 2.1 AA标准的4.5:1对比度。对于标题角色，使用
```
mj-html-attributes
```
— 在严格验证规则下，直接在
```
mj-text
```
上设置
```
role
```
/
```
aria-level
```
属性是不允许的（请参考下方的可访问性检查清单）。
样式效率 — 使用
```
<mj-attributes>
```
结合
```
<mj-all>
```
、组件默认值和
```
<mj-class>
```
来消除重复的内联样式。
首屏横幅板块 — 使用
```
<mj-hero>
```
实现全屏宽度的首屏横幅；在不支持的客户端中会回退为普通板块。避免使用
```
<mj-accordion>
```
和
```
<mj-carousel>
```
— 客户端支持度极低，实用性差。
模板支持 — 将动态标签（Handlebars/Liquid）包裹在
```
<mj-raw>
```
中，避免被MJML解析器处理。

Critical Gotchas

关键注意事项

Outlook:

Background images: VML only generated for
```
<mj-section>
```
and
```
<mj-hero>
```
— nowhere else
Background positioning: keyword values only (
```
top
```
,
```
center
```
,
```
bottom
```
) — pixel values ignored

Always pair

background-repeat="no-repeat"

with explicit

background-size

Font fallback:
```
<mj-font>
```
hides
```
@font-face
```
from Outlook via MSO conditional comments

Gmail:

Use component attributes for critical layout — CSS classes may be stripped
102KB clip: always compile with
```
--config.minify=true
```

iOS / Android stacking:

Always compile with
```
--config.minify=true
```
— removes whitespace between
```
inline-block
```
columns
Whitespace between tags causes stacking even inside
```
<mj-group>
```

Vertical-align bug:

If any column in a section sets
```
vertical-align
```
, ALL columns in that section must explicitly set it

JavaScript:

JS is completely blocked in all email clients (Gmail, Outlook, Apple Mail, iOS Mail). No
```
onclick
```
, no clipboard API, no interactivity of any kind. Interactive-looking elements (copy buttons, toggles) are purely decorative.

Outlook相关：

背景图片：仅会为
```
<mj-section>
```
和
```
<mj-hero>
```
生成VML代码 — 其他标签不支持
背景定位：仅支持关键字值（
```
top
```
、
```
center
```
、
```
bottom
```
） — 像素值会被忽略

始终将

background-repeat="no-repeat"

与明确的

background-size

配合使用

字体回退：
```
<mj-font>
```
通过MSO条件注释隐藏
```
@font-face
```
，避免Outlook出现问题

Gmail相关：

使用组件属性设置关键布局 — CSS类可能会被移除
102KB截断限制：编译时始终添加
```
--config.minify=true
```
参数

iOS / Android堆叠问题：

编译时始终添加
```
--config.minify=true
```
参数 — 移除
```
inline-block
```
列之间的空白
标签之间的空白会导致即使在
```
<mj-group>
```
内的元素也发生堆叠

垂直对齐Bug：

如果某个板块中的任意列设置了
```
vertical-align
```
，该板块中的所有列必须显式设置此属性

JavaScript：

所有邮件客户端（Gmail、Outlook、Apple Mail、iOS Mail）完全禁止JS。不支持
```
onclick
```
、剪贴板API或任何交互功能。看似可交互的元素（复制按钮、切换控件）仅为装饰性。

Dark Mode Pattern

深色模式方案

xml

<mj-head>
  <mj-raw>
    <meta name="color-scheme" content="light dark">
    <meta name="supported-color-schemes" content="light dark">
  </mj-raw>

  <!-- Light logo visible by default; dark logo hidden -->
  <mj-style inline="inline">
    .dark-logo { display: none !important; }
  </mj-style>

  <!-- Dark mode overrides -->
  <mj-style>
    @media (prefers-color-scheme: dark) {
      .light-logo { display: none !important; }
      .dark-logo  { display: block !important; }
    }
  </mj-style>
</mj-head>

Safe neutrals:

#121212

(not

#000000

) and

#F1F1F1

(not

#FFFFFF

) — prevents jarring forced inversions.

xml

<mj-head>
  <mj-raw>
    <meta name="color-scheme" content="light dark">
    <meta name="supported-color-schemes" content="light dark">
  </mj-raw>

  <!-- Light logo visible by default; dark logo hidden -->
  <mj-style inline="inline">
    .dark-logo { display: none !important; }
  </mj-style>

  <!-- Dark mode overrides -->
  <mj-style>
    @media (prefers-color-scheme: dark) {
      .light-logo { display: none !important; }
      .dark-logo  { display: block !important; }
    }
  </mj-style>
</mj-head>

安全中性色：

#121212

（而非

#000000

）和

#F1F1F1

（而非

#FFFFFF

） — 避免刺眼的强制反转效果。

Accessibility Checklist

可访问性检查清单

```
<mj-title>
```
is set (screen reader email label +
```
aria-label
```
)
```
lang
```
attribute on root
```
<mjml>
```
tag
```
alt
```
on every
```
<mj-image>
```
and
```
<mj-social-element>
```

Heading role set via

mj-html-attributes

(NOT as a direct attribute on

mj-text

xml

<!-- In mj-head -->
<mj-html-attributes>
  <mj-selector path=".email-heading div">
    <mj-html-attribute name="role">heading</mj-html-attribute>
    <mj-html-attribute name="aria-level">1</mj-html-attribute>
  </mj-selector>
</mj-html-attributes>
<!-- On the component -->
<mj-text css-class="email-heading" ...>Heading text</mj-text>

4.5:1 contrast ratio on all text/background pairs
No text baked into images — always use live
```
<mj-text>
```
blocks

设置
```
<mj-title>
```
（屏幕阅读器邮件标签 +
```
aria-label
```
）
根
```
<mjml>
```
标签上设置
```
lang
```
属性
每个
```
<mj-image>
```
和
```
<mj-social-element>
```
都设置
```
alt
```
属性

通过

mj-html-attributes

设置标题角色（而非直接在

mj-text

上设置属性）：

xml

<!-- In mj-head -->
<mj-html-attributes>
  <mj-selector path=".email-heading div">
    <mj-html-attribute name="role">heading</mj-html-attribute>
    <mj-html-attribute name="aria-level">1</mj-html-attribute>
  </mj-selector>
</mj-html-attributes>
<!-- On the component -->
<mj-text css-class="email-heading" ...>Heading text</mj-text>

所有文本/背景组合的对比度达到4.5:1
图片中不能包含文本 — 始终使用可编辑的
```
<mj-text>
```
块

Component Index

组件索引

Before writing any MJML, read the component file(s) for the components you'll use.

Group	Components	Load when	File
Head	mj-attributes, mj-font, mj-style, mj-preview, mj-breakpoint, mj-html-attributes	Setting up head, global styles	`components/head.md`
Layout	mj-body, mj-section, mj-column, mj-group, mj-wrapper	Building structure / grid	`components/layout.md`
Content	mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-table	Adding content blocks	`components/content.md`
Interactive	mj-accordion, mj-carousel, mj-social, mj-navbar	Interactive or social elements	`components/interactive.md`
Advanced	mj-hero, mj-raw, mj-include	Hero banners, template tags, partials	`components/advanced.md`

General reference (hierarchy, ending tags, validation, width math, Gmail clip):

mjml-reference.md

在编写任何MJML代码前，请先阅读你将使用的组件对应的文件。

分组	组件	加载时机	文件
头部	mj-attributes, mj-font, mj-style, mj-preview, mj-breakpoint, mj-html-attributes	设置头部、全局样式	`components/head.md`
布局	mj-body, mj-section, mj-column, mj-group, mj-wrapper	构建结构/网格	`components/layout.md`
内容	mj-text, mj-image, mj-button, mj-divider, mj-spacer, mj-table	添加内容块	`components/content.md`
交互	mj-accordion, mj-carousel, mj-social, mj-navbar	交互或社交元素	`components/interactive.md`
进阶	mj-hero, mj-raw, mj-include	首屏横幅、模板标签、片段	`components/advanced.md`

通用参考（层级、闭合标签、验证、宽度计算、Gmail截断）：

mjml-reference.md

Compilation

编译

Read

compilation.md

for the full workflow. Key command:

bash

npx mjml template.mjml -o dist/template.html --config.minify=true --config.validationLevel=strict

Hard rules:

Never
```
npm install -g mjml
```
Always use
```
npx
```
or
```
./node_modules/.bin/mjml
```
If mjml not in
```
package.json
```
, suggest
```
npm install -D mjml
```

完整工作流请查看

compilation.md

。核心命令：

bash

npx mjml template.mjml -o dist/template.html --config.minify=true --config.validationLevel=strict

硬性规则：

切勿使用
```
npm install -g mjml
```
全局安装
始终使用
```
npx
```
或
```
./node_modules/.bin/mjml
```
如果package.json中未包含mjml，建议执行
```
npm install -D mjml
```

Examples

示例

assets/examples/basic-layout.mjml

— MJML docs basic layout example. Covers 6-section structure: company header, image hero + button, intro text, 2-column image+text, 3-column icons, social row. Intentionally bare-bones (no

mj-head

, no dark mode, placeholder copy) — reflects the MJML docs style. Use as a structural reference for layout patterns only, not as a production template.

assets/examples/basic-layout.mjml

— MJML文档中的基础布局示例。包含6板块结构：公司页眉、图片首屏+按钮、介绍文本、双栏图片+文本、三栏图标、社交行。故意设计得非常简洁（无

mj-head

、无深色模式、占位文本） — 与MJML文档风格一致。仅将其用作布局模式的结构参考，而非生产模板。

Output

输出要求

Always deliver:

<name>.mjml
— complete MJML source (editable, version-controllable)
<name>.html
— compiled output (production-ready, send via ESP)

Name files after the email type:

welcome.mjml

promo-sale.mjml

order-confirmation.mjml

始终交付以下两个文件：

<name>.mjml
— 完整的MJML源文件（可编辑、可版本控制）
<name>.html
— 编译后的输出文件（可用于生产环境，通过ESP发送）

根据邮件类型命名文件：

welcome.mjml

、

promo-sale.mjml

、

order-confirmation.mjml