feat: MJML docs

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"

content/cli/email-layout.mdx

@@ -14,7 +14,7 @@ Email layout commands enable you to manage email layouts in your Knock account f
 <Section title="Layout file structure" path="/email-layout/file-structure">
 <ContentColumn>
 
-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 */}
 <PreTextDiagram description="Local layout files structure">

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 `<mjml>` tag instead of an HTML document. Plain HTML within an MJML layout must be wrapped in `<mjml-raw>` tags.
+
 <Callout
   emoji="🌠"
   title="Note:"
   text={
     <>
-      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 <code>&lt;mjml&gt;</code> root tag.
     </>
   }
 />

content/integrations/email/mjml.mdx

@@ -0,0 +1,66 @@
+---
+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 `<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.
+
+```mjml title="MJML layout with mjml-raw for HTML"
+<mjml>
+  <mj-head>
+    <mj-title>Welcome</mj-title>
+  </mj-head>
+  <mj-body>
+    <mj-section>
+      <mj-column> {{ content }} </mj-column>
+    </mj-section>
+    <mj-section>
+      <mj-column>
+        <mjml-raw> {{ footer_links }} </mjml-raw>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
+```
+
+[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 `<mjml-raw>` tags. This means you can include HTML snippets in your MJML and they will render correctly.
+
+<Callout
+  emoji="🌠"
+  title="Note:"
+  text={
+    <>
+      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 <code>&lt;mjml-raw&gt;</code> tags so it renders correctly within the
+      MJML document.
+    </>
+  }
+/>
+
+## Limitations
+
+- **MJML layouts require the `<mjml>` 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 `<mjml-raw>` automatically.

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.

content/template-editor/email-templates.mdx

@@ -77,6 +77,8 @@ Knock provides client-specific previews of your email templates, powered by Litm
 
 <AccordionGroup>
   <Accordion title="Can I use MJML to write my email templates?">
-    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.
   </Accordion>
 </AccordionGroup>

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.
 
+<Callout
+  emoji="🌠"
+  title="Note:"
+  text={
+    <>
+      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 <code>&lt;mjml-raw&gt;</code> tags automatically. See the{" "}
+      <a href="/integrations/email/mjml">MJML support</a> docs for details.
+    </>
+  }
+/>
+
 Learn more about partials in the [Partials overview](/template-editor/partials/overview) page.
 
 ## Enabling HTML partials as blocks

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 <a href="https://cursor.com/learn/context" target="_blank">guide on working with context</a> 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.
 

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" },