From b5f62e2a0a7f2eea15359e9abacf40e06c39096f Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Tue, 17 Mar 2026 21:38:05 -0400 Subject: [PATCH 1/3] feat: MJML docs --- components/ui/CodeBlock.tsx | 3 + content/cli/email-layout.mdx | 2 +- content/integrations/email/layouts.mdx | 7 +- content/integrations/email/mjml.mdx | 78 +++++++++++++++++++ content/integrations/email/overview.mdx | 1 + content/template-editor/email-templates.mdx | 4 +- .../partials/html-partials.mdx | 13 ++++ .../migrate-email-with-mcp-server.mdx | 2 +- data/sidebars/integrationsSidebar.ts | 1 + 9 files changed, 106 insertions(+), 5 deletions(-) create mode 100644 content/integrations/email/mjml.mdx diff --git a/components/ui/CodeBlock.tsx b/components/ui/CodeBlock.tsx index b67df6532..0d3e9c2c2 100644 --- a/components/ui/CodeBlock.tsx +++ b/components/ui/CodeBlock.tsx @@ -14,6 +14,7 @@ import yaml from "react-syntax-highlighter/dist/cjs/languages/hljs/yaml"; import kotlin from "react-syntax-highlighter/dist/cjs/languages/hljs/kotlin"; import swift from "react-syntax-highlighter/dist/cjs/languages/hljs/swift"; import bash from "react-syntax-highlighter/dist/cjs/languages/hljs/bash"; +import xml from "react-syntax-highlighter/dist/cjs/languages/hljs/xml"; import { useClipboard } from "@/hooks/useClipboard"; import { useTheme } from "@/components/theme/ThemeProvider"; @@ -44,6 +45,8 @@ SyntaxHighlighter.registerLanguage("yaml", yaml); SyntaxHighlighter.registerLanguage("curl", bash); SyntaxHighlighter.registerLanguage("swift", swift); SyntaxHighlighter.registerLanguage("kotlin", kotlin); +SyntaxHighlighter.registerLanguage("xml", xml); +SyntaxHighlighter.registerLanguage("mjml", xml); export type SupportedLanguage = | "javascript" diff --git a/content/cli/email-layout.mdx b/content/cli/email-layout.mdx index a8f75c5ce..10403d286 100644 --- a/content/cli/email-layout.mdx +++ b/content/cli/email-layout.mdx @@ -14,7 +14,7 @@ Email layout commands enable you to manage email layouts in your Knock account f
-When email layouts are pulled from Knock, they are stored in directories named by their layout key. +When email layouts are pulled from Knock, they are stored in directories named by their layout key. MJML layouts use the same file structure; the `html_layout.html` file contains MJML markup instead of HTML. See the [MJML support](/integrations/email/mjml) docs for details. {/* prettier-ignore */} diff --git a/content/integrations/email/layouts.mdx b/content/integrations/email/layouts.mdx index 6a909c296..c0e431a57 100644 --- a/content/integrations/email/layouts.mdx +++ b/content/integrations/email/layouts.mdx @@ -72,13 +72,16 @@ If you'd like to create an email step in your workflow that contains the full HT If you want to create your own custom email layouts, you can go into the layout editor and click "Edit in code editor" to go to an HTML and CSS editor for your email layout. The important thing to remember here is that your layout needs a `{{content}}` somewhere in its `body` tag for the email template to be injected into the layout. +Layouts can also be set to use [MJML](/integrations/email/mjml). When a layout uses MJML, it must contain a root `` tag instead of an HTML document. Plain HTML within an MJML layout must be wrapped in `` tags. + - if you're providing a custom HTML layout for your emails, the layout must - be a valid HTML document. + If you're providing a custom HTML layout for your emails, the layout must + be a valid HTML document. For MJML layouts, the layout must be a valid + MJML document with the <mjml> root tag. } /> diff --git a/content/integrations/email/mjml.mdx b/content/integrations/email/mjml.mdx new file mode 100644 index 000000000..7f4478f3b --- /dev/null +++ b/content/integrations/email/mjml.mdx @@ -0,0 +1,78 @@ +--- +title: MJML support +description: Learn how to use MJML to build responsive email layouts and templates in Knock. +section: Integrations +layout: integrations +tags: + [ + "mjml", + "responsive", + "email", + "layouts", + "templates", + "mobile", + ] +--- + +Knock supports [MJML](https://mjml.io/), 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. + +## MJML layouts + +You can set an email layout to use MJML. When a layout is configured for MJML, it must contain a root `` 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 `` tags. MJML will pass through the contents of `` without compiling them, so you can use standard HTML where needed. + +```mjml title="MJML layout with mjml-raw for HTML" + + + Welcome + + + + + {{ content }} + + + + + + {{ footer_links }} + + + + + +``` + +[Learn more about email layouts](/integrations/email/layouts). + +## MJML templates + +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. + +## Mixing HTML and MJML + +Knock automatically wraps plain HTML inside MJML templates and layouts in `` tags. This means you can include HTML snippets in your MJML and they will render correctly. + + + HTML partials cannot include MJML. Partials must be HTML. When an HTML + partial is used inside an MJML template, Knock wraps the partial's content + in <mjml-raw> tags so it renders correctly within the + MJML document. + + } +/> + +## Limitations + +- **MJML layouts require the `` root tag.** Layouts set to MJML mode must be valid MJML documents. +- **HTML partials cannot include MJML.** [HTML partials](/template-editor/partials/html-partials) must contain HTML only. When used in an MJML template, their content is wrapped in `` automatically. \ No newline at end of file diff --git a/content/integrations/email/overview.mdx b/content/integrations/email/overview.mdx index 133b75318..ef28e61a0 100644 --- a/content/integrations/email/overview.mdx +++ b/content/integrations/email/overview.mdx @@ -15,6 +15,7 @@ Effortlessly design and deliver email notifications to downstream providers, wit - **CSS inlining**: By default, Knock will inline all CSS included with your emails to ensure maximum compatibility across email clients. - **Text generation**: We'll automatically generate a text version of your emails, so you never need to write both HTML and text templates. - **Multiple layouts**: We support any number of emails layouts that can "wrap" your email templates and provide styles and shared elements like headers and footers. +- **MJML support**: Use [MJML](/integrations/email/mjml) to build responsive email layouts and templates with built-in mobile compatibility. - **Attachments support**: It's easy to send attachments alongside your emails, just pass through some Base64 encoded data along with your `workflow.trigger` call and you're done! - **Knock link and open tracking**: Capture link-click and email-open events right within your Knock account. For more details, see the [Knock link and open tracking documentation](/send-notifications/tracking). - **Per environment configuration**: Configure different settings for each environment in your Knock account. diff --git a/content/template-editor/email-templates.mdx b/content/template-editor/email-templates.mdx index 0d13b565e..3d3ef22b5 100644 --- a/content/template-editor/email-templates.mdx +++ b/content/template-editor/email-templates.mdx @@ -77,6 +77,8 @@ Knock provides client-specific previews of your email templates, powered by Litm - No, currently Knock does not support MJML for email templates. + Yes. Knock supports MJML for both email layouts and templates. You can use + MJML in the code editor or via the visual block editor. See the [MJML + support](/integrations/email/mjml) docs for details. diff --git a/content/template-editor/partials/html-partials.mdx b/content/template-editor/partials/html-partials.mdx index 08bcedc37..4bb6617b0 100644 --- a/content/template-editor/partials/html-partials.mdx +++ b/content/template-editor/partials/html-partials.mdx @@ -8,6 +8,19 @@ section: Working with templates HTML partials are reusable components that can be used across any of your email templates. You can use HTML partials in Knock to create an email design system to empower your product and marketing teams to create consistent, brand-compliant emails. + + HTML partials must contain HTML and cannot include MJML markup. When an + HTML partial is used inside an MJML template, Knock wraps the partial's + content in <mjml-raw> tags automatically. See the{" "} + [MJML support](/integrations/email/mjml) docs for details. + + } +/> + Learn more about partials in the [Partials overview](/template-editor/partials/overview) page. ## Enabling HTML partials as blocks diff --git a/content/tutorials/migrate-email-with-mcp-server.mdx b/content/tutorials/migrate-email-with-mcp-server.mdx index a76434326..53650f0ce 100644 --- a/content/tutorials/migrate-email-with-mcp-server.mdx +++ b/content/tutorials/migrate-email-with-mcp-server.mdx @@ -24,7 +24,7 @@ Before getting started, you'll need access to the following: - A [Knock account](https://dashboard.knock.app/). - A configured [email provider](/integrations/email/overview) in your Knock account. Navigate to **Integrations** > **Channels** in your dashboard to set this up if you haven't already done so. - An MCP-compatible client (such as Cursor, Claude Code, or Claude Desktop). We recommend Cursor for working with a large collection of HTML files. -- Your existing email template files. Your templates will be upserted to Knock as HTML, so if you're using a format like MJML or React Email, you'll want to convert them to HTML before you begin. +- Your existing email template files. Your templates will be upserted to Knock as HTML, so if you're using React Email or another format, you'll want to convert them to HTML before you begin. Knock supports [MJML](/integrations/email/mjml) natively, so MJML templates do not need to be converted. For the purposes of this tutorial, we will assume that you're familiar with prompting an agentic LLM and understand how to provide access to files as context for your prompts. If you're not sure what this means, we recommend checking out this guide on working with context from Cursor. For more information on setting up the Knock MCP server, see the [Get started](/developer-tools/mcp-server#get-started) section of the MCP documentation. diff --git a/data/sidebars/integrationsSidebar.ts b/data/sidebars/integrationsSidebar.ts index a1e6b8b65..230ef7dd7 100644 --- a/data/sidebars/integrationsSidebar.ts +++ b/data/sidebars/integrationsSidebar.ts @@ -31,6 +31,7 @@ export const INTEGRATIONS_SIDEBAR: SidebarContent[] = [ pages: [ { slug: "/overview", title: "Overview" }, { slug: "/layouts", title: "Layouts" }, + { slug: "/mjml", title: "MJML" }, { slug: "/settings", title: "Settings and overrides" }, { slug: "/attachments", title: "Sending attachments" }, { slug: "/client-previews", title: "Client previews" }, From 7bfb5075e3324dec1c010ffb8c416e3c3f01e4a6 Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Wed, 18 Mar 2026 15:18:12 -0400 Subject: [PATCH 2/3] chore: fmt --- content/integrations/email/mjml.mdx | 20 ++++--------------- .../partials/html-partials.mdx | 4 ++-- 2 files changed, 6 insertions(+), 18 deletions(-) diff --git a/content/integrations/email/mjml.mdx b/content/integrations/email/mjml.mdx index 7f4478f3b..05d0dea8d 100644 --- a/content/integrations/email/mjml.mdx +++ b/content/integrations/email/mjml.mdx @@ -3,15 +3,7 @@ title: MJML support description: Learn how to use MJML to build responsive email layouts and templates in Knock. section: Integrations layout: integrations -tags: - [ - "mjml", - "responsive", - "email", - "layouts", - "templates", - "mobile", - ] +tags: ["mjml", "responsive", "email", "layouts", "templates", "mobile"] --- Knock supports [MJML](https://mjml.io/), 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. @@ -29,15 +21,11 @@ To include plain HTML within an MJML layout, wrap it in `` tags. MJML - - {{ content }} - + {{ content }} - - {{ footer_links }} - + {{ footer_links }} @@ -75,4 +63,4 @@ Knock automatically wraps plain HTML inside MJML templates and layouts in `` root tag.** Layouts set to MJML mode must be valid MJML documents. -- **HTML partials cannot include MJML.** [HTML partials](/template-editor/partials/html-partials) must contain HTML only. When used in an MJML template, their content is wrapped in `` automatically. \ No newline at end of file +- **HTML partials cannot include MJML.** [HTML partials](/template-editor/partials/html-partials) must contain HTML only. When used in an MJML template, their content is wrapped in `` automatically. diff --git a/content/template-editor/partials/html-partials.mdx b/content/template-editor/partials/html-partials.mdx index 4bb6617b0..7adabba5e 100644 --- a/content/template-editor/partials/html-partials.mdx +++ b/content/template-editor/partials/html-partials.mdx @@ -15,8 +15,8 @@ HTML partials are reusable components that can be used across any of your email <> HTML partials must contain HTML and cannot include MJML markup. When an HTML partial is used inside an MJML template, Knock wraps the partial's - content in <mjml-raw> tags automatically. See the{" "} - [MJML support](/integrations/email/mjml) docs for details. + content in <mjml-raw> tags automatically. See the [MJML + support](/integrations/email/mjml) docs for details. } /> From 46225bb9d776cc31481d234b947a77e4dee61854 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 18 Mar 2026 20:38:12 +0000 Subject: [PATCH 3/3] fix: use tag instead of markdown link inside JSX expression Markdown link syntax is not processed inside JSX expressions in MDX, so [MJML support](/integrations/email/mjml) rendered as literal text. Replaced with an tag to create a proper clickable link. Co-authored-by: Chris Bell --- content/template-editor/partials/html-partials.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/template-editor/partials/html-partials.mdx b/content/template-editor/partials/html-partials.mdx index 7adabba5e..56c3a218f 100644 --- a/content/template-editor/partials/html-partials.mdx +++ b/content/template-editor/partials/html-partials.mdx @@ -15,8 +15,8 @@ HTML partials are reusable components that can be used across any of your email <> HTML partials must contain HTML and cannot include MJML markup. When an HTML partial is used inside an MJML template, Knock wraps the partial's - content in <mjml-raw> tags automatically. See the [MJML - support](/integrations/email/mjml) docs for details. + content in <mjml-raw> tags automatically. See the{" "} + MJML support docs for details. } />