docs: Update email layouts, MJML, and client previews documentation #1500
+154
−22
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -77,6 +77,71 @@ The following MJML tags do not have their HTML children wrapped: | |
| } | ||
| /> | ||
|
|
||
| ## Dark mode support in MJML layouts | ||
|
|
||
| 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: | ||
|
|
||
| ```mjml title="MJML layout with dark mode support" | ||
| <mjml> | ||
| <mj-head> | ||
| <mj-raw> | ||
| <meta name="color-scheme" content="light dark" /> | ||
| <meta name="supported-color-schemes" content="light dark" /> | ||
| </mj-raw> | ||
| <mj-style> | ||
| :root { color-scheme: light dark; supported-color-schemes: light dark; } | ||
| @media (prefers-color-scheme: dark) { .email-wrapper, .email-body { | ||
| background-color: #262626 !important; } p, h1, h2, h3 { color: #ffffff | ||
| !important; } } | ||
| </mj-style> | ||
| </mj-head> | ||
| <mj-body> | ||
| <!-- layout content --> | ||
| </mj-body> | ||
| </mjml> | ||
| ``` | ||
|
|
||
| For swapping logos and icons in dark mode, see [Swapping logos and icons in dark mode](/integrations/email/layouts#swapping-logos-and-icons-in-dark-mode) in the email layouts documentation. | ||
|
There was a problem hiding this comment. Repeated layouts links on MJML pageLow Severity This page already links to Additional Locations (1)  Triggered by learned rule: Link Knock concepts on first mention only per page Reviewed by Cursor Bugbot for commit 5819a6a. Configure here. |
||
|
|
||
| ## Styling buttons in MJML layouts | ||
|
|
||
| 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. | ||
|
|
||
| #### How branding colors are applied | ||
|
|
||
| - **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` and `dark_primary_color_contrast` (falling back to the light mode values if not set). | ||
|
|
||
| ```mjml title="MJML branding-aware button styling" | ||
| <mj-style> | ||
| /* Light mode button styles */ .block-button--solid { background-color: {{ | ||
| vars.branding.primary_color | default: "#000000" }}; color: {{ | ||
| vars.branding.primary_color_contrast | default: "#FFFFFF" }}; } | ||
| .block-button--outline { background-color: transparent; color: {{ | ||
| vars.branding.primary_color | default: "#000000" }}; border-color: {{ | ||
| vars.branding.primary_color | default: "#000000" }}; } /* Dark mode overrides | ||
| */ @media (prefers-color-scheme: dark) { .block-button--solid { | ||
| background-color: {{ vars.branding.dark_primary_color | default: | ||
| vars.branding.primary_color | default: "#000000" }} !important; color: {{ | ||
| vars.branding.dark_primary_color_contrast | default: | ||
| vars.branding.primary_color_contrast | default: "#FFFFFF" }} !important; } | ||
| .block-button--outline { background-color: transparent !important; color: {{ | ||
| vars.branding.dark_primary_color | default: vars.branding.primary_color | | ||
| default: "#000000" }} !important; border-color: {{ | ||
| vars.branding.dark_primary_color | default: vars.branding.primary_color | | ||
| default: "#000000" }} !important; } } | ||
| </mj-style> | ||
| ``` | ||
|
|
||
| #### Why dark mode uses `!important` overrides | ||
|
|
||
| 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](/integrations/email/layouts#styling-buttons) in the email layouts documentation. | ||
|
|
||
| ## Limitations | ||
|
|
||
| - **MJML layouts require the `<mjml>` root tag.** Layouts set to MJML mode must be valid MJML documents. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -45,13 +45,17 @@ Use the [tenant API methods](/api-reference/tenants) to create or update a tenan | |
|
|
||
| ### `TenantSettings` | ||
|
|
||
| | Property | Description | | ||
| | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | ||
| | `branding.logo_url` | A fully qualified URL for an image to use as the logo of this tenant | | ||
| | `branding.icon_url` | A fully qualified URL for an image to use as the icon of this tenant | | ||
| | `branding.dark_logo_url` | A fully qualified URL for the logo to use in dark mode. Defaults to `logo_url` if not set | | ||
| | `branding.dark_icon_url` | A fully qualified URL for the icon to use in dark mode. Defaults to `icon_url` if not set | | ||
| | `branding.primary_color` | A hex value for the primary color. Defaults to `#000000` | | ||
| | `branding.primary_color_contrast` | A hex value for the contrasting color to use with the primary color. Defaults to `#FFFFFF` | | ||
| | `branding.dark_primary_color` | A hex value for the primary color in dark mode. Defaults to `primary_color` if not set | | ||
| | `branding.dark_primary_color_contrast` | A hex value for the contrasting color in dark mode. Defaults to `primary_color_contrast` if not set | | ||
| | `preference_set` | A complete `PreferenceSet` to use as a default for all recipients with workflows triggered for this tenant | | ||
|
Comment on lines
+48
to
+58
Member
There was a problem hiding this comment. This is only tangential to this PR, but should we ticket adding these properties to the OpenAPI spec so that they're included in
Contributor
Author
There was a problem hiding this comment. Ah yep we should. Could you file ticket for that? |
||
|
|
||
| <Callout | ||
| type="alert" | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.