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.

The Knock default MJML layout supports dark mode out of the box via the prefers-color-scheme CSS media query. To add dark mode support to a custom MJML layout, include the color scheme meta tags and CSS overrides in your <mj-head>:

The Knock default MJML layout wires button styles to your branding colors so buttons match your brand out of the box. This applies to both the legacy .button class and the visual editor's .block-button components.

• Solid buttons (.block-button--solid). Background uses primary_color, text uses primary_color_contrast. In dark mode, these switch to dark_primary_color and dark_primary_color_contrast.

• Outline buttons (.block-button--outline). Transparent background with primary_color text and border. In dark mode, these switch to dark_primary_color.

In light mode, per-button colors set in the visual editor take precedence. In dark mode, the layout applies !important to override inline styles and ensure readability on dark backgrounds.

The visual editor renders button colors as static inline styles that do not change between light and dark mode. Without layout-level overrides, buttons would display their light-mode colors on a dark background, making text unreadable. The layout uses !important in dark mode to force branding colors on all buttons.

Here's the CSS to add branding-aware buttons to a custom MJML layout:

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 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.