MJML support

Knock supports MJML, a responsive email framework that compiles to HTML optimized for email clients. MJML abstracts away the complexity of table-based layouts and media queries, so you can build responsive emails that look great across devices with less code.

You can set an email layout to use MJML. When a layout is configured for MJML, it must contain a root <mjml> tag. The layout structure works the same as HTML layouts: the {{content}} variable receives the template content, and {{footer_links}} receives footer links when configured.

To include plain HTML within an MJML layout, wrap it in <mjml-raw> tags. MJML will pass through the contents of <mjml-raw> without compiling them, so you can use standard HTML where needed.

Learn more about email layouts.

Email templates can use MJML in two ways:

1. Full template. Write your entire template in MJML in the code editor. MJML templates can be used with "No layout" (standalone) or within an MJML layout.
2. Visual block editor. Use the visual editor to compose your template. When the template or its layout is MJML, the blocks render as MJML components.

When you use an MJML template with a layout, the layout must also be MJML. When you use "No layout," the template stands alone as a complete MJML document.

Knock automatically wraps plain HTML inside MJML templates and layouts in <mjml-raw> tags when the HTML appears at the <mj-body>, <mj-section>, or <mj-column> level. This means you can include HTML snippets in your MJML templates and they will render correctly.

Knock skips auto-wrapping of HTML when the parent element is an MJML ending tag. Ending tags are MJML components that expect plain HTML or text content as their direct children by spec.

The following MJML tags do not have their HTML children wrapped:

• <mj-accordion-text>
• <mj-accordion-title>
• <mj-button>
• <mj-navbar-link>
• <mj-preview>
• <mj-social-element>
• <mj-style>
• <mj-table>
• <mj-text>
• <mj-title>

MJML layouts support dark mode using the prefers-color-scheme media query. The Knock default MJML layout includes dark mode support out of the box, automatically swapping colors and images based on the user's system preference.

To add dark mode support to a custom MJML layout, include the color scheme meta tags in <mj-head> and define your dark mode styles in an <mj-style> block:

For swapping logos and icons in dark mode, see Swapping logos and icons in dark mode in the email layouts documentation.

The Knock default MJML layout styles buttons using your branding colors, with automatic dark mode support. This applies to both legacy mj-button components and visual editor buttons.

• Solid buttons use primary_color as the background and primary_color_contrast as the text color.
• Outline buttons use a transparent background with primary_color as the text and border color.
• Dark mode uses dark_primary_color (defaults to #FFFFFF) and dark_primary_color_contrast (defaults to #000000).

The visual editor renders button colors as static inline styles that don't change between light and dark mode. To ensure buttons remain readable on dark backgrounds, the layout uses !important in dark mode to override these inline styles. This means per-button colors from the visual editor are respected in light mode, while dark mode enforces branding-aware colors for readability.

For more details, see Styling buttons in the email layouts documentation.

• MJML layouts require the <mjml> root tag. Layouts set to MJML mode must be valid MJML documents.
• Partials cannot include MJML. HTML partials must contain HTML only. When used in an MJML template, their content is automatically wrapped in <mjml-raw> tags where appropriate.