# API Reference (/docs/api-reference)



render(markdown, options?) [#rendermarkdown-options]

Renders markdown to email-safe HTML. **Async** since v0.3.0; returns a `Promise`.

**Returns** `Promise<{ html, text, meta, warnings? }>`

* `html`: complete HTML email document
* `text`: plain text version for the `text/plain` MIME part
* `meta`: extracted frontmatter metadata
* `warnings`: non-fatal issues encountered while rendering (e.g. invalid frontmatter YAML). Omitted when empty. See [`RenderWarning`](#renderwarning).

```typescript
import { render } from "emailmd";

const { html, text, meta } = await render("# Hello");
```

RenderOptions [#renderoptions]

```typescript
{
  theme?: Partial<Theme>;
  wrapper?: 'default' | WrapperFn;
  minify?: boolean;
  fonts?: Record<string, string>;
  validationLevel?: 'skip' | 'soft' | 'strict';
  templateSyntax?: Array<{ prefix: string; suffix: string }>;
  sanitizeStyles?: boolean;
  beautify?: boolean;
  strings?: RenderStrings;
  darkTheme?: true | Partial<Theme>;
  breaks?: boolean;
  allowHtml?: boolean;
  css?: string;
  partials?: Record<string, string>;
}
```

| Option            | Type                                        | Description                                                                                                                                                                                                                                                                                                                   |
| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme`           | `Partial<Theme>`                            | Override default theme values                                                                                                                                                                                                                                                                                                 |
| `wrapper`         | `'default' \| WrapperFn`                    | Custom email wrapper function                                                                                                                                                                                                                                                                                                 |
| `minify`          | `boolean`                                   | Minify output HTML. Default `false`.                                                                                                                                                                                                                                                                                          |
| `fonts`           | `Record<string, string>`                    | Custom web fonts: `{ [family]: url }` rendered as `<mj-font>`.                                                                                                                                                                                                                                                                |
| `validationLevel` | `'skip' \| 'soft' \| 'strict'`              | MJML validation level. Default `'soft'`.                                                                                                                                                                                                                                                                                      |
| `templateSyntax`  | `Array<{ prefix: string; suffix: string }>` | Template delimiters preserved during compilation. Default `[{{...}}, [[...]]]`.                                                                                                                                                                                                                                               |
| `sanitizeStyles`  | `boolean`                                   | Sanitize template variables inside CSS before minification. Requires `minify: true`.                                                                                                                                                                                                                                          |
| `beautify`        | `boolean`                                   | Pretty-print output HTML. Ignored when `minify: true`. Default `false`.                                                                                                                                                                                                                                                       |
| `strings`         | `RenderStrings`                             | Override output strings for localization. See [`RenderStrings`](#renderstrings).                                                                                                                                                                                                                                              |
| `darkTheme`       | `true \| Partial<Theme>`                    | Opt into [automatic dark mode](/docs/theme#automatic-dark-mode). `true` = built-in dark palette; a partial theme merges over it. Overridden by a pinned frontmatter `theme: light`/`dark`.                                                                                                                                    |
| `breaks`          | `boolean`                                   | Render single newlines as `<br>`. Frontmatter `breaks:` wins per document. Default `false`.                                                                                                                                                                                                                                   |
| `allowHtml`       | `boolean`                                   | Allow raw HTML tags in the Markdown source. Default `true` (raw tags pass through). Set `false` to escape raw tags (`<script>` → text) while keeping every Markdown feature. See [Raw HTML](#raw-html).                                                                                                                       |
| `css`             | `string`                                    | Custom CSS emitted as one extra `<mj-style>` in the head, after the built-in styles so it can override them. Reaches renderer classes like `.emd-btn`. Inline styles still win, so use `!important`, and as an embedded `<style>` not every client honours it. Trusted developer input only, not end-user-controlled strings. |
| `partials`        | `Record<string, string>`                    | Named markdown [partials](/docs/partials) spliced in at `::: include <name>` lines.                                                                                                                                                                                                                                           |

RenderResult [#renderresult]

```typescript
{
  html: string;
  text: string;
  meta: { preheader?: string; [key: string]: unknown };
  warnings?: RenderWarning[];
}
```

| Property   | Type               | Description                                                           |
| ---------- | ------------------ | --------------------------------------------------------------------- |
| `html`     | `string`           | Complete email-safe HTML document                                     |
| `text`     | `string`           | Plain text version                                                    |
| `meta`     | `object`           | Extracted frontmatter metadata                                        |
| `warnings` | `RenderWarning[]?` | Non-fatal issues (e.g. invalid frontmatter YAML). Omitted when empty. |

RenderWarning [#renderwarning]

```typescript
{
  stage: 'frontmatter' | 'theme' | 'content' | 'mjml';
  message: string;
  cause?: Error;
}
```

| Property  | Type     | Description                                         |
| --------- | -------- | --------------------------------------------------- |
| `stage`   | `string` | Which render stage produced the warning (see below) |
| `message` | `string` | Human-readable message                              |
| `cause`   | `Error?` | Original thrown error, when one is available        |

Warnings never stop the render: `html`/`text` output always contains a working email, so UIs can keep the preview alive and surface warnings alongside it. The stages:

| Stage         | Meaning                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `frontmatter` | The YAML block could not be parsed. The body renders with empty `meta`.                                                                          |
| `theme`       | A theme or font value was invalid (e.g. contained markup) and the default was used instead.                                                      |
| `content`     | A directive or button value was invalid (an unknown color, alignment, length, or unsafe URL) and was dropped or replaced with the theme default. |
| `mjml`        | The MJML compiler reported a validation error (at the default `soft` level).                                                                     |

lint(markdown, options?) [#lintmarkdown-options]

Check an email for deliverability, accessibility, and readability problems. Unlike [render warnings](#renderwarning), which report things emailmd had to repair, lint findings flag content that renders fine but is likely to hurt the email in practice. Returns a `Promise<LintFinding[]>`, sorted by source line:

```typescript
import { lint } from 'emailmd';

const findings = await lint(markdown, { partials });
// [{ rule: 'image-alt', severity: 'warning',
//    message: 'Image is missing alt text — …', line: 12 }]
```

```typescript
interface LintFinding {
  rule: string;                          // machine-readable rule id
  severity: 'warning' | 'suggestion';    // warning = likely real problem
  message: string;
  line?: number;                         // 1-based line in the source markdown
}
```

The full rule list, severity semantics, and CLI and builder integration are documented on the [Linting](/docs/linting) page. Template tokens are respected throughout: a `{{tracking_url}}` link is never flagged insecure, and `[Unsubscribe]({{unsubscribe_url}})` satisfies the unsubscribe check.

Input validation [#input-validation]

All user-supplied values that end up in the HTML are escaped and/or validated before interpolation:

* The frontmatter `preheader` is HTML-escaped.
* Directive params must be plausible values: colors must be hex, named, `rgb()`/`rgba()`, or `hsl()`/`hsla()`; alignment must be `left`, `center`, or `right`; lengths must be CSS length tokens like `8px` or `50%`.
* Hero background URLs with `javascript:`, `data:`, `vbscript:`, or `file:` schemes are dropped.
* Theme values containing `<`, `>`, or `"` are replaced with the base theme's value.
* Font entries with unsafe family names or URLs are skipped.

Invalid values never throw; they fall back to safe defaults and surface as [`warnings`](#renderwarning). Template tags (`{{ x }}`, `{% x %}`, `${x}`, `%%x%%`, `[[x]]`) pass through validation untouched so merge fields keep working. Note that raw inline HTML in the markdown body is passed through by design: treat the markdown source as trusted, and resolve template variables with properly encoded values in your sending app.

RenderStrings [#renderstrings]

Overridable output strings, for localization:

```typescript
{
  buttonFallback?: string;
}
```

`buttonFallback` is the sentence shown under a button rendered with the `fallback` attribute. It supports the placeholders `{text}` (the button label) and `{url}` (a clickable copy of the button link), and may contain HTML entities:

```typescript
await render(md, {
  strings: {
    buttonFallback: 'Probleme mit &bdquo;{text}&ldquo;? Nutzen Sie diesen Link: {url}',
  },
});
```

A per-button `fallback="custom text"` attribute still takes precedence over the global string. See [Buttons](/docs/buttons#button-fallback).

Theme [#theme]

The full theme interface with all customizable properties:

```typescript
interface Theme {
  brandColor: string;       // Links, highlights, accents
  headingColor: string;     // Heading text
  bodyColor: string;        // Body text
  backgroundColor: string;  // Outer background
  contentColor: string;     // Content area background
  cardColor: string;        // Callout / code block background
  buttonColor: string;      // Primary button background
  buttonTextColor: string;  // Button text
  secondaryColor: string;   // Secondary button border
  secondaryTextColor: string; // Secondary button text
  successColor: string;     // Success button background
  successTextColor: string; // Success button text
  dangerColor: string;      // Danger button background
  dangerTextColor: string;  // Danger button text
  warningColor: string;     // Warning button background
  warningTextColor: string; // Warning button text
  fontFamily: string;       // Font stack
  fontSize: string;         // Base font size (e.g. "16px")
  lineHeight: string;       // Base line height (e.g. "1.6")
  contentWidth: string;     // Email width (e.g. "600px")
  borderRadius: string;     // Border radius for buttons, callouts (e.g. "8px")
}
```

Pass a `Partial<Theme>` to `render()` to override any subset of values. See [Theme](/docs/theme) for defaults.

darkTheme [#darktheme]

A pre-built dark theme object. Import and pass directly or spread with overrides:

```typescript
import { render, darkTheme } from "emailmd";

// Use as-is
await render(md, { theme: darkTheme });

// Override specific values
await render(md, { theme: { ...darkTheme, brandColor: "#e11d48" } });
```

buildHead(theme, preheader?) [#buildheadtheme-preheader]

```typescript
function buildHead(theme: Theme, preheader?: string): string;
```

Generates the MJML `<mj-head>` element containing global styles, font imports, and the hidden preheader text. Used when building [custom wrappers](/docs/wrappers).

segmentsToMjml(segments, theme, ctx?) [#segmentstomjmlsegments-theme-ctx]

```typescript
function segmentsToMjml(
  segments: Segment[],
  theme: Theme,
  ctx?: { strings?: RenderStrings; warnings?: RenderWarning[] },
): string;
```

Converts parsed content segments into MJML body elements (sections, columns, text, buttons, images, tables, etc.). Used when building [custom wrappers](/docs/wrappers).

The optional `ctx` argument forwards localized [`strings`](#renderstrings) and a `warnings` array to collect [content validation issues](#input-validation) during segment rendering. Custom wrappers should pass through the values they receive on `meta` (the default wrapper does) so those warnings surface on the render result.

Segment [#segment]

```typescript
interface Segment {
  type: 'text' | 'callout' | 'centered' | 'highlight' | 'header' | 'footer'
      | 'button' | 'button-group' | 'image' | 'hr' | 'table' | 'hero';
  content: string;
  attrs?: Record<string, string>;
  buttons?: Array<Record<string, string>>;
}
```

Represents a parsed block of content from the markdown. The `segments` array is what gets passed to `segmentsToMjml` and to custom wrapper functions.

WrapperFn [#wrapperfn]

```typescript
type WrapperFn = (
  segments: Segment[],
  theme: Theme,
  meta?: WrapperMeta,
) => string;
```

A function that receives parsed segments, the resolved theme, and render context, and returns a complete MJML string. See [Wrappers](/docs/wrappers) for usage examples.

WrapperMeta [#wrappermeta]

The context object passed to wrapper functions:

```typescript
{
  preheader?: string;
  frontmatter?: Record<string, unknown>;
  strings?: RenderStrings;
  warnings?: RenderWarning[];
}
```

| Property      | Type                       | Description                                                        |
| ------------- | -------------------------- | ------------------------------------------------------------------ |
| `preheader`   | `string?`                  | Preheader text from frontmatter                                    |
| `frontmatter` | `Record<string, unknown>?` | The full frontmatter map, including custom keys                    |
| `strings`     | `RenderStrings?`           | Localized strings from render options; forward to `segmentsToMjml` |
| `warnings`    | `RenderWarning[]?`         | The render's warnings collector; forward to `segmentsToMjml`       |

Sanitize helpers [#sanitize-helpers]

The validation primitives used internally are exported for reuse:

```typescript
import { escapeHtml, escapeAttrValue, isCssColor, isCssLength, isSafeUrl } from "emailmd";
```

* **`escapeHtml(value)`**: escape a raw string for HTML text or attribute context
* **`escapeAttrValue(value)`**: escape `"` and `<` without double-escaping existing entities
* **`isCssColor(value)`**: hex, named, `rgb()`/`hsl()` functional color, or template token
* **`isCssLength(value)`**: 1–4 CSS length tokens (e.g. `8px 16px`), or template token
* **`isSafeUrl(value)`**: no scheme, a safe scheme (`http`, `https`, `mailto`, `tel`), or template token

Raw HTML [#raw-html]

By default (`allowHtml: true`) raw HTML in the Markdown source passes through verbatim: `<span style="…">`, `<div>`, and inline tags like `<u>` all render as written. This is convenient for templates you control.

Set `allowHtml: false` to escape raw tags to text instead:

```typescript
const { html } = await render(markdown, { allowHtml: false });
```

Now `<script>alert(1)</script>` renders as the literal characters rather than an element, while every Markdown feature (headings, emphasis, links, lists, tables, images, emoji, directives, buttons) keeps working. `javascript:`/`data:` URLs in Markdown links are blocked either way.

`allowHtml: false` also closes the two other ways Markdown can emit markup:

* **Attribute syntax.** The `{attr=…}` syntax attaches attributes to the generated element (`# Hi {onclick=…}` becomes `<h1 onclick="…">`). In this mode event handlers (`on*`), inline `style`, and `href`/`src` overrides with a `javascript:`/`data:` scheme are dropped. Harmless attributes (`class`, `id`, `data-*`, and emailmd's own `button`, `caption`, `width`, `align`) are kept, so buttons, captions, and classes still work.
* **Template tags.** Raw HTML wrapped in a template tag (`{{<script>…</script>}}`) is escaped to text instead of spliced back verbatim. A legitimate template variable like `{{ profile_url }}` has no HTML-significant characters, so it stays unchanged.

This is not a general HTML sanitizer. It prevents injection through emailmd's own syntax, but if your threat model demands high assurance, run the output through a dedicated sanitizer (tag/attribute allowlist) as a second layer.


# Buttons (/docs/buttons)



Add call-to-action buttons using the `{button}` attribute:

```markdown
[Get Started](https://example.com){button}

[Learn More](https://example.com){button.secondary}

[Shop Sale](https://example.com){button color="#dc2626"}
```

Semantic Colors [#semantic-colors]

Use preset color names for common actions:

```markdown
[Confirm Account](https://example.com/confirm){button.success}

[Delete Account](https://example.com/delete){button.danger}

[Review Changes](https://example.com/review){button.warning}
```

These default to standard semantic colors (green, red, amber). You can customize them with `success_color`, `danger_color`, and `warning_color` in [frontmatter](/docs/frontmatter) or via the [theme API](/docs/theme). The secondary button color can be changed with `secondary_color`.

Side-by-Side Buttons [#side-by-side-buttons]

Place multiple buttons on the same line to render them side-by-side:

```markdown
[Get Started](https://example.com){button} [Learn More](https://example.com/more){button.secondary}
```

Buttons on separate lines (separated by a blank line) stack vertically as usual. MJML handles responsive stacking automatically: side-by-side on desktop, stacked on mobile.

Full-Width Buttons [#full-width-buttons]

Make a button span the full width of the email content area with `width="full"`:

```markdown
[Get Started](https://example.com){button width="full"}
```

This works with any variant or custom color:

```markdown
[Learn More](https://example.com){button.secondary width="full"}

[Shop Sale](https://example.com){button color="#dc2626" width="full"}
```

Border Radius [#border-radius]

Override the default border radius (`8px`) on individual buttons with `border-radius="..."`:

```markdown
[Get Started](https://example.com){button border-radius="24px"}

[Sharp](https://example.com){button border-radius="0"}
```

To change the default border radius for all buttons (and callouts/highlights), set `border_radius` in [frontmatter](/docs/frontmatter) or via the [theme API](/docs/theme).

Size [#size]

Buttons take their font size from the theme's `fontSize`, so they scale with the body text. A smaller `fontSize` gives a smaller button.

Styling [#styling]

Every button carries the class `emd-btn`, so you can reach properties that have no dedicated option (weight, padding, …) through the [`css`](/docs/api-reference#renderoptions) render option:

```typescript
await render(md, {
  css: '.emd-btn a { font-weight: 400 !important }',
});
```

The `!important` is needed because the button's own styles are inline. Because this relies on an embedded `<style>`, treat it as progressive enhancement: clients that don't honour those keep the built-in styling.

The `css` string is emitted verbatim, so pass it only trusted developer input, never end-user-controlled strings.

Button Fallback [#button-fallback]

Add a fallback URL below a button for accessibility. Some email clients block or strip buttons, so providing the raw URL ensures recipients can still take action:

```markdown
[Reset Password](https://example.com/reset){button fallback}
```

This renders a small muted text below the button: *"If you're having trouble clicking the button, copy and paste this URL into your browser."*

Works with button groups too; only buttons with `fallback` show their URL:

```markdown
[Accept](https://example.com/accept){button fallback} [Decline](https://example.com/decline){button.secondary}
```

Custom Fallback Text [#custom-fallback-text]

Override the default fallback message with `fallback="custom text"` to support different languages or custom wording:

```markdown
[Réinitialiser](https://example.com/reset){button fallback="Si vous avez des difficultés, copiez cette URL :"}
```

The custom text is rendered before the URL link. When no value is provided (`fallback` without `="..."`), the default English message is used.

To change the default message globally instead of per button, pass `strings.buttonFallback` to `render()`. It supports `{text}` and `{url}` placeholders:

```typescript
await render(md, {
  strings: {
    buttonFallback: "Si vous avez des difficultés avec le bouton « {text} », copiez cette URL : {url}",
  },
});
```

A per-button `fallback="..."` attribute still wins over the global string. See [`RenderStrings`](/docs/api-reference#renderstrings).


# CLI (/docs/cli)



emailmd ships with a built-in CLI.

Install [#install]

If emailmd is already a project dependency, you can run it via `npx`:

```bash
npx emailmd input.md
```

To install it as a global command:

```bash
npm install -g emailmd
```

Usage [#usage]

```bash
emailmd [file] [options]
emailmd lint [file] [options]
emailmd mcp [options]
```

If no file is given, the CLI reads from stdin. The `lint` command checks the email instead of rendering it; see [Linting](#linting) below. The `mcp` command runs the [MCP server](/docs/mcp) for AI clients; see [MCP Server](#mcp-server) below.

Options [#options]

| Option                  | Description                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| `-o, --output <f>`      | Write output to a file instead of stdout                                                                      |
| `-t, --text`            | Output plain text instead of HTML                                                                             |
| `-m, --minify`          | Minify the HTML output                                                                                        |
| `-b, --beautify`        | Pretty-print the HTML output (ignored with `-m`)                                                              |
| `--escape-html`         | Escape raw HTML for untrusted input. See [Raw HTML](/docs/api-reference#raw-html).                            |
| `-p, --partials <path>` | [Partials](/docs/partials) for `::: include <name>`: a directory of `.md` files or a single file. Repeatable. |
| `--strict`              | `lint` only: exit non-zero on suggestions as well                                                             |
| `-h, --help`            | Show help                                                                                                     |
| `-v, --version`         | Show version number                                                                                           |

Examples [#examples]

Render a markdown file to HTML:

```bash
emailmd input.md
```

Write the output to a file:

```bash
emailmd input.md -o output.html
```

Get the plain text version (for the `text/plain` MIME part):

```bash
emailmd input.md --text
```

Minify the HTML output (useful for staying under Gmail's 102KB clip limit):

```bash
emailmd input.md --minify -o output.html
```

Pretty-print the HTML output (handy for reading it straight in the terminal):

```bash
emailmd input.md --beautify
```

Escape raw HTML when the source is untrusted, so raw tags render as text instead of markup. This also drops unsafe `{attr=…}` attributes and escapes HTML inside template tags. See [Raw HTML](/docs/api-reference#raw-html):

```bash
emailmd untrusted.md --escape-html -o safe.html
```

Load [partials](/docs/partials) from a directory. Each `.md` file becomes a partial named after its path relative to the directory, so `partials/blocks/legal.md` is included as `::: include blocks/legal`. Individual files work too (named by basename), and the flag is repeatable with later paths winning on name collisions:

```bash
emailmd input.md --partials ./partials
emailmd input.md -p ./partials -p ./extra/legal.md
```

Pipe from another command:

```bash
echo "# Hello" | emailmd
curl -s https://example.com/template.md | emailmd -o email.html
```

Linting [#linting]

`emailmd lint` checks the email for deliverability, accessibility, and readability problems instead of rendering it: missing alt text, `http://` links, Gmail's 102KB clip limit, generic link text, spam-trigger phrases, and more. See [Linting](/docs/linting) for the full rule list.

```bash
emailmd lint input.md
emailmd lint input.md --partials ./partials
```

```
   5  warning     Image is missing alt text — screen readers and blocked-image clients show nothing.  (image-alt)
  12  suggestion  Link text "click here" says nothing out of context — describe the destination instead.  (link-text)

2 problems (1 warning, 1 suggestion)
```

The exit code is `1` when warnings are found, so it slots into CI; suggestions alone exit `0` unless you pass `--strict`.

MCP Server [#mcp-server]

`emailmd mcp` runs the [MCP server](/docs/mcp) over stdio, giving a local AI client tools to render, lint, and look up docs. `--partials` preloads [partials](/docs/partials) for every render and lint call:

```bash
emailmd mcp
emailmd mcp --partials ./partials
```


# Emoji (/docs/emoji)



Insert emoji by shortcode name using the `:shortcode:` syntax:

```markdown
Gone camping! :tent: Be back soon.

That is so funny! :joy:
```

The full set of \~1900 emoji shortcodes from [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) is supported. Emoji are rendered as native Unicode characters, so they display natively in all modern email clients without image fallbacks.

Common Examples [#common-examples]

| Shortcode            | Emoji | Shortcode    | Emoji |
| -------------------- | ----- | ------------ | ----- |
| `:smile:`            | 😄    | `:heart:`    | ❤️    |
| `:wave:`             | 👋    | `:fire:`     | 🔥    |
| `:rocket:`           | 🚀    | `:star:`     | ⭐     |
| `:thumbsup:`         | 👍    | `:tada:`     | 🎉    |
| `:white_check_mark:` | ✅     | `:warning:`  | ⚠️    |
| `:email:`            | 📧    | `:calendar:` | 📅    |

Usage in Emails [#usage-in-emails]

```markdown
:wave: **Welcome aboard!**

Your order has been confirmed :white_check_mark:

:calendar: Delivery expected: Friday
```

Full Shortcode Reference [#full-shortcode-reference]

Use the [emoji picker in the builder](/builder) to search all available shortcodes, or see the [full emoji list](https://gist.github.com/rxaviers/7360908).


# Frontmatter (/docs/frontmatter)



Add a YAML frontmatter block at the top of your markdown to override theme values and set metadata per-email:

```markdown
---
preheader: "Don't miss our biggest sale"
brand_color: "#e11d48"
button_color: "#059669"
---

# Sale Starts Now

Everything is 50% off this weekend.

::: footer
**Acme Corp** · [Unsubscribe](https://example.com/unsub)
:::
```

Frontmatter uses `snake_case` keys. They map directly to the same [theme options](/docs/theme) available in the JS API (which uses `camelCase`).

Preheader [#preheader]

The `preheader` field sets the preview text that email clients show in the inbox list next to the subject line. It's hidden in the email body itself:

```markdown
---
preheader: "Your order has shipped. Track it now"
---
```

Selecting a Theme [#selecting-a-theme]

Use `theme` to switch the base theme for a single email. Individual overrides still layer on top:

```markdown
---
theme: dark
brand_color: "#e11d48"
---

# Dark email with a custom brand color
```

Valid values: `light` (default), `dark`, `auto`.

Automatic Dark Mode [#automatic-dark-mode]

`theme: dark` renders the email dark for everyone. `theme: auto` renders light by default but adapts to readers whose mail client is in dark mode:

```markdown
---
theme: auto
---
```

To tune the dark variant, override parts of the built-in dark palette with a `dark:` map (same `snake_case` keys as the light theme). A `dark:` map on its own implies `theme: auto`:

```markdown
---
theme: auto
dark:
  background_color: "#111827"
  content_color: "#1f2937"
---
```

Explicitly pinning `theme: light` or `theme: dark` renders static: it overrides the [`darkTheme` render option](/docs/theme#automatic-dark-mode) when the sending app enables dark mode globally. See [Theme → Automatic Dark Mode](/docs/theme#automatic-dark-mode) for client support notes.

Custom Fonts [#custom-fonts]

Embed custom web fonts (e.g. Google Fonts) with a nested `fonts:` map. Each entry is a family name → stylesheet URL, rendered as a `<mj-font>` tag so the font loads in clients that support embedded web fonts (Apple Mail, iOS Mail):

```markdown
---
fonts:
  Inter: "https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap"
  Merriweather: "https://fonts.googleapis.com/css2?family=Merriweather"
font_family: "Inter, sans-serif"
---

# Hello
```

The font still needs to be named in `font_family` (or via `fontFamily` in code) to actually apply to text. MJML only injects a `<link>` for fonts referenced in the compiled CSS, so unused entries are silently dropped.

When both the `fonts:` frontmatter and the `fonts` [render option](/docs/api-reference#renderoptions) are provided, frontmatter wins on matching family names and non-overlapping entries merge together.

Language and Direction [#language-and-direction]

Set `lang` (a language tag like `en`, `de`, or `pt-BR`) and `dir` (`ltr`, `rtl`, or `auto`) to emit the matching attributes on the output document's `<html>` tag, so screen readers pick the right voice and right-to-left scripts lay out correctly:

```markdown
---
lang: ar
dir: rtl
---

# مرحبا
```

When unset, the output uses MJML's defaults (`lang="und" dir="auto"`).

`dir: rtl` does more than set the attribute: the default text alignment flips to right (email clients don't do this for you; MJML hardcodes left alignment), and left-anchored details like blockquote bars and list indents flip with it. Explicit alignment parameters (`center`, `left`, `right` on directives and images) still apply as written.

Hard Line Breaks [#hard-line-breaks]

By default, a single newline does not break a line (standard markdown; use a blank line for a new paragraph). Set `breaks: true` to render every newline as a line break, the way non-technical writers usually expect:

```markdown
---
breaks: true
---

Line one
Line two renders below it
```

Apps can set this globally with the `breaks` [render option](/docs/api-reference#renderoptions); the frontmatter value wins per document.

All Frontmatter Keys [#all-frontmatter-keys]

| Key                    | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| `preheader`            | Inbox preview text (hidden in email body)                                     |
| `theme`                | Appearance: `light`, `dark`, or `auto` (adapts to the reader's dark mode)     |
| `brand_color`          | Links, highlights, accents                                                    |
| `heading_color`        | Heading text color                                                            |
| `body_color`           | Body text color                                                               |
| `background_color`     | Outer background color                                                        |
| `content_color`        | Content area background                                                       |
| `card_color`           | Callout / code block background                                               |
| `button_color`         | Primary button background                                                     |
| `button_text_color`    | Button text color                                                             |
| `secondary_color`      | Secondary button border                                                       |
| `secondary_text_color` | Secondary button text                                                         |
| `success_color`        | Success button background                                                     |
| `success_text_color`   | Success button text                                                           |
| `danger_color`         | Danger button background                                                      |
| `danger_text_color`    | Danger button text                                                            |
| `warning_color`        | Warning button background                                                     |
| `warning_text_color`   | Warning button text                                                           |
| `divider_color`        | Horizontal rule (`---`) color                                                 |
| `font_family`          | Font stack                                                                    |
| `font_size`            | Base font size                                                                |
| `line_height`          | Base line height                                                              |
| `content_width`        | Email content width                                                           |
| `border_radius`        | Border radius for buttons, callouts, highlights                               |
| `fonts`                | Nested map of custom web fonts: family name → stylesheet URL                  |
| `dark`                 | Map of dark-palette overrides for `theme: auto` (implies `auto` when present) |
| `lang`                 | Document language tag (e.g. `en`, `pt-BR`) for the output `<html>`            |
| `dir`                  | Text direction: `ltr`, `rtl`, or `auto`                                       |
| `breaks`               | `true` renders single newlines as line breaks                                 |

Frontmatter values are validated before rendering: theme values containing markup characters fall back to the base theme, font entries with unsafe URLs are skipped, and the preheader is HTML-escaped in the output. Invalid values never break the render; they surface on [`warnings`](/docs/api-reference#renderwarning) instead.

Custom Metadata [#custom-metadata]

Any keys beyond the ones above are passed through in the `meta` object returned by `render()`. This is useful for storing email metadata alongside the template:

```markdown
---
preheader: "Welcome aboard"
subject: "Welcome to Acme"
campaign_id: "onboarding-v2"
---

# Welcome!
```

```typescript
const { html, text, meta } = await render(markdown);

console.log(meta.subject);     // "Welcome to Acme"
console.log(meta.campaign_id); // "onboarding-v2"
console.log(meta.preheader);   // "Welcome aboard"
```


# Getting Started (/docs/getting-started)



Installation [#installation]

```bash
npm install emailmd
```

Basic Usage [#basic-usage]

Import the `render` function and pass it a markdown string:

```typescript
import { render } from "emailmd";

const { html, text } = await render(`
# Welcome!

Thanks for signing up.

[Get Started](https://example.com){button}
`);
```

`render` is asynchronous, so `await` it (or use `.then()`).

The `render` function returns:

* `html`: a complete HTML document (DOCTYPE, html, head, body) ready to use as the `text/html` MIME part. It's not a fragment; you can send it as-is.
* `text`: the plain text version for the `text/plain` MIME part. Buttons become `Label: https://url`, images become `[Image: alt]`, and all formatting is stripped.
* `meta`: frontmatter metadata extracted from the markdown, including `preheader` (inbox preview text) and any custom keys you define. See [Frontmatter](/docs/frontmatter).

Next Steps [#next-steps]

* [Builder](/builder): write markdown and watch the email render live
* [Templates](/templates): production-ready designs to start from
* [Buttons](/docs/buttons): add call-to-action buttons
* [Directives](/docs/directives): heroes, columns, callouts, and more
* [Theme](/docs/theme): customize colors, fonts, and dark mode
* [API Reference](/docs/api-reference): full API documentation


# Images (/docs/images)



Block images (standalone paragraph) are automatically rendered as responsive, centered email images:

```markdown
![Hero banner](https://picsum.photos/seed/banner/1200/500)
```

Width [#width]

Control image width with the attrs syntax:

```markdown
![Product](https://picsum.photos/seed/product/800/600){width="400"}
```

Alignment [#alignment]

Images are centered by default. Override with:

```markdown
![Photo](https://picsum.photos/seed/photo/600/400){align="left"}
```

Rounded Corners [#rounded-corners]

```markdown
![Avatar](https://picsum.photos/seed/avatar/160/160){width="80" border-radius="50%"}
```

Captions [#captions]

Add a `caption` to render a small, muted line under the image. It follows the image's alignment and appears after the image label in the plain-text version:

```markdown
![Signups chart](https://picsum.photos/seed/chart/800/450){caption="Figure 1: signups by week"}
```

Captions are plain text; markdown and HTML inside them are not processed.

Linked Images [#linked-images]

Wrap an image in a link to make it clickable:

```markdown
[![Shop banner](https://picsum.photos/seed/shop/1200/400)](https://example.com/shop)
```

Inline Images [#inline-images]

Images mixed with text in a paragraph are rendered inline:

```markdown
Feature one with icon ![check](https://placehold.co/20x20.png) included.
```

Vertical Alignment [#vertical-alignment]

Inline images default to `vertical-align: middle`, centering them with adjacent text. Override per image with `valign`:

```markdown
Top-aligned ![icon](https://placehold.co/20x20.png){valign="top"} icon.
```

Supported values: `top`, `middle`, `bottom`, `baseline`, `text-top`, `text-bottom`.

Float [#float]

Use `float` to wrap text around an image instead of flowing beneath it:

```markdown
![Plant](https://picsum.photos/seed/plant/160/160){width="80" float="left"} **Monstera Deliciosa, 6" pot** Easy care · Bright indirect light · $42.00
```

Supported values: `left`, `right`. Appropriate margin is added automatically.

> **Note:** Outlook desktop ignores `float` and falls back to default inline behavior.

Inline Image Size [#inline-image-size]

Control inline image dimensions with `width` and `height`:

```markdown
A small ![icon](https://placehold.co/40x40.png){width="20" height="20"} icon.
```

Formats and Retina Sizing [#formats-and-retina-sizing]

Stick to **PNG, JPEG, and GIF**, which every email client renders. The formats to avoid:

* **SVG** is stripped by Gmail, Outlook, and most other clients.
* **`data:` URIs** are stripped by Gmail's image proxy and clients like it, so always host images at a URL.
* **WebP and AVIF** work in Apple Mail and Gmail, but Outlook desktop and some older clients show a broken image.

[`lint()`](/docs/linting) flags all of these under the `image-format` rule.

For crisp images on high-DPI screens, use the standard email retina technique: serve an image with **twice the pixels** you display and set the rendered size with `width`:

```markdown
![Product](https://example.com/product-800.jpg){width="400"}
```

The photo examples on this page follow this pattern (an 800×600 source displayed at 400).

Placeholder Images [#placeholder-images]

While drafting, use placeholder services so every image actually renders. The examples on this page follow this convention, so they all work if you paste them into the [builder](/builder):

* **Photos:** `https://picsum.photos/seed/<name>/<width>/<height>` returns a random but stable photo. The same seed always returns the same image, so pick a new seed name for each distinct image.
* **Logos, icons, and flat graphics:** `https://placehold.co/<width>x<height>.png?text=Logo` renders a solid box with an optional label. The `.png` extension matters: the service defaults to SVG, which most email clients won't display.
* **Hero backgrounds:** random photos make overlaid text unreadable when they're too bright. Route the photo through the [wsrv.nl](https://wsrv.nl) image proxy with a dark duotone filter, which remaps the photo's full tonal range between two dark colors, so light text stays readable no matter which photo the seed produces:

```markdown
::: hero https://wsrv.nl/?url=picsum.photos/seed/hero/1200/600&filt=duotone&start=111827&stop=4b5563
# Always readable
The photo's brightest pixel is only as light as `stop`.
:::
```

Swap `start`/`stop` (darkest and lightest hex colors, no `#`) to tint toward your brand. For a light background with dark text instead, use light colors and set `color=` on the hero.

Placeholders are for drafts. Replace them with real, self-hosted assets before sending; [`lint()`](/docs/linting) flags images on known placeholder hosts as a reminder.


# Introduction (/docs)



Why emailmd? [#why-emailmd]

Writing good email HTML is genuinely hard. Email clients never adopted a shared rendering engine: Outlook still renders with Microsoft Word's engine, Gmail strips `<style>` tags and most CSS, and Yahoo Mail has quirks of its own. A layout that looks perfect in Apple Mail can be completely broken in Outlook. That's why hand-built emails end up as deeply nested tables, inline styles, and client-specific hacks.

Most teams either settle for plain-looking emails, hire a specialist, or wrestle with templating systems that demand deep knowledge of each client's limitations.

emailmd takes a different approach. You write **markdown**, the same syntax you already use in README files, docs, and chat. emailmd converts it into bulletproof, email-safe HTML (via MJML) that renders correctly in Gmail, Outlook, Apple Mail, Yahoo Mail, and every other major client.

It won't cover every edge case a hand-crafted HTML email can, but it handles **80%+ of email design needs** in a fraction of the time and complexity.

Quick Start [#quick-start]

```bash
npm install emailmd
```

```typescript
import { render } from "emailmd";

const { html, text } = await render(`
# Welcome!

Thanks for signing up.

[Get Started](https://example.com){button}
`);

// html → complete email-safe HTML (works in Gmail, Outlook, Apple Mail, everything)
// text → plain text version for text/plain MIME part
```

Prefer a visual starting point? The [builder](/builder) renders your markdown to a live preview as you type, and the [template gallery](/templates) has twelve production-ready designs to copy and make your own.

Features [#features]

* **Email-safe HTML.** MJML under the hood, tested across Gmail, Outlook, Apple Mail, Yahoo Mail, and more.
* **Layout that flexes.** Photo [heroes](/docs/directives/hero), responsive [columns](/docs/directives/columns), [callouts](/docs/directives/callout), [accordions](/docs/directives/accordion), and the rest of the [directives](/docs/directives).
* **Theming and dark mode.** Brand colors, custom fonts, and [automatic dark mode](/docs/theme#automatic-dark-mode) that follows the reader's preference.
* **Buttons.** Primary, secondary, and semantic [button](/docs/buttons) variants with one attribute.
* **Frontmatter.** Per-email [theme overrides and metadata](/docs/frontmatter) that live with the content.
* **Linting.** [Deliverability and accessibility checks](/docs/linting) that catch problems before you send.
* **Plain text.** An automatic `text/plain` version alongside every render.
* **Tooling.** A [CLI](/docs/cli), a drop-in [React builder](/docs/react), an [MCP server](/docs/mcp) for AI assistants, and reusable [partials](/docs/partials).

AI-Friendly by Design [#ai-friendly-by-design]

Because it's just markdown, AI tools are a natural fit. Language models are great at writing markdown, so you can describe the email you want and get a working, production-ready template in seconds.

The [MCP server](/docs/mcp) closes the loop: connect it to Claude, ChatGPT, Cursor, or any other MCP client and the assistant doesn't just write the email, it lints the draft, renders the final HTML, and hands you a live preview link. For AI tools without MCP support, feed them the complete docs instead:

```
https://www.emailmd.dev/llms-full.txt
```

Built on MJML [#built-on-mjml]

emailmd uses [MJML](https://mjml.io) under the hood for bulletproof email HTML. Tested across Gmail, Outlook, Apple Mail, Yahoo Mail, and more.


# Linting (/docs/linting)



Rendering tells you the email works. Linting tells you whether it will land well. `lint()` checks an email for problems that render fine but hurt it in practice: missing alt text, `http://` links, Gmail's 102KB clip limit, generic link text, spam-trigger phrases, and more.

```typescript
import { lint } from 'emailmd';

const findings = await lint(markdown);
// [{ rule: 'image-alt', severity: 'warning',
//    message: 'Image is missing alt text — …', line: 12 }]
```

Each finding carries a machine-readable `rule` id, a `severity`, a human-readable `message`, and the 1-based `line` in the source markdown. See the [API reference](/docs/api-reference#lintmarkdown-options) for the full signature.

Severities [#severities]

* **warning**: likely a real problem. Fix these before sending.
* **suggestion**: worth a look, but often intentional (a transactional email may deliberately skip the unsubscribe link, for example).

Rules [#rules]

| Rule                | Severity             | Checks                                                                                                        |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `image-alt`         | warning              | Images without alt text                                                                                       |
| `insecure-link`     | warning              | Links or image sources using `http://`                                                                        |
| `gmail-clip`        | warning              | Minified HTML over 102KB (Gmail clips the message)                                                            |
| `render`            | warning              | Render warnings, folded in so one call surfaces everything                                                    |
| `image-format`      | warning / suggestion | SVG and `data:` images, stripped by most clients (warning); WebP/AVIF, broken in Outlook desktop (suggestion) |
| `link-text`         | suggestion           | Generic link text ("click here", "here", "link")                                                              |
| `preheader-missing` | suggestion           | No `preheader` in frontmatter                                                                                 |
| `preheader-length`  | suggestion           | Preheader longer than \~100 characters (inbox previews truncate)                                              |
| `unsubscribe`       | suggestion           | No unsubscribe link anywhere in the rendered output                                                           |
| `spam-words`        | suggestion           | Common spam-filter trigger phrases ("act now", "100% free", …)                                                |
| `placeholder-image` | suggestion           | Images or hero backgrounds on placeholder hosts (picsum.photos, placehold.co, wsrv.nl, …)                     |

Template tokens are respected throughout: a `{{tracking_url}}` link is never flagged insecure, and `[Unsubscribe]({{unsubscribe_url}})` satisfies the unsubscribe check.

In the CLI [#in-the-cli]

`emailmd lint` runs the same checks from the terminal and prints findings with line numbers:

```bash
emailmd lint input.md
```

The exit code is `1` when warnings are found, so it slots into CI; suggestions alone exit `0` unless you pass `--strict`. See [CLI → Linting](/docs/cli#linting).

In the Builder [#in-the-builder]

Pass the `lint` prop to [`<EmailmdBuilder />`](/docs/react#emailmdbuilder-) (or the `lint` option to `useEmailmd`) and findings surface live alongside render warnings as you type.


# Markdown (/docs/markdown)



emailmd supports standard markdown plus several extensions. This page covers the features that aren't covered by their own dedicated docs pages ([buttons](/docs/buttons), [images](/docs/images), [tables](/docs/tables), [emoji](/docs/emoji), and [directives](/docs/directives)).

Text Formatting [#text-formatting]

Standard inline formatting works as expected:

```markdown
**Bold text** and *italic text* and ***bold italic***.

~~Strikethrough~~ for deleted content.

`inline code` renders with a subtle background.
```

Headings [#headings]

```markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
```

Headings are styled with the theme's `headingColor`.

Links [#links]

```markdown
[Visit our site](https://example.com)

Autolinks work too: https://example.com
```

Links are styled with the theme's `brandColor`.

Lists [#lists]

Ordered and unordered lists:

```markdown
- First item
- Second item
- Third item

1. Step one
2. Step two
3. Step three
```

Task Lists [#task-lists]

```markdown
- [x] Design approved
- [x] Content written
- [ ] Ready to send
```

Task lists render with checkboxes: checked items show a filled box, unchecked items an empty one.

Blockquotes [#blockquotes]

```markdown
> "The best way to predict the future is to create it."
>
> — Peter Drucker
```

Blockquotes are styled with a left border in your theme's `brandColor`.

Code Blocks [#code-blocks]

Fenced code blocks render with a theme-aware background:

````markdown
```
const greeting = "Hello, world!";
console.log(greeting);
```
````

The background uses the theme's `cardColor` with rounded corners and comfortable padding.

Syntax Highlighting [#syntax-highlighting]

Name a language on the fence and the code is syntax-highlighted with email-safe markup, no external stylesheets or scripts:

````markdown
```ts
const greeting: string = "Hello, world!";
```
````

Supported languages (aliases in parentheses): JavaScript (`js`, `jsx`), TypeScript (`ts`, `tsx`), HTML/XML (`html`), CSS, JSON, YAML (`yml`), Bash (`sh`), Shell (`console`), Python (`py`), Go, Rust (`rs`), Java, C# (`cs`), PHP, Ruby (`rb`), SQL, and Diff.

Token colors adapt to the theme: a dark `card_color` gets a light-on-dark palette automatically, and `theme: auto` emails switch palettes with the reader's dark mode. Unknown languages (or fences with no language) render as plain code, so omitting the language is the opt-out.

Definition Lists [#definition-lists]

```markdown
emailmd
: A markdown-to-email library.

MJML
: The framework that powers emailmd's HTML output.
```

Highlighted Text [#highlighted-text]

Use `==double equals==` to highlight text with a colored background:

```markdown
Don't miss our ==biggest sale of the year==!
```

The highlight uses your theme's `brandColor` at reduced opacity.

Subscript & Superscript [#subscript--superscript]

```markdown
H~2~O is water.

E = mc^2^ is famous.
```

`~text~` renders as subscript, `^text^` renders as superscript.

Horizontal Rules [#horizontal-rules]

A horizontal rule creates a visual separator between sections:

```markdown
Thanks for reading!

---

*The Acme Team*
```


# MCP Server (/docs/mcp)



emailmd ships a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect it to Claude, ChatGPT, Cursor, or any other MCP client and the assistant can render markdown to email-safe HTML, lint drafts for deliverability problems, look up these docs, and hand you a live preview link for every draft. Instead of writing an email *about* emailmd syntax and hoping it works, your AI writes one, checks it, and shows you the result.

Connect a Client [#connect-a-client]

<McpInstallButtons />

The hosted server speaks Streamable HTTP at:

```
https://www.emailmd.dev/api/mcp
```

It is stateless and unauthenticated: every request is independent, and nothing you render is stored. Markdown and partial inputs are capped at 256KB each, far beyond any legitimate email (Gmail clips at 102KB).

* **Claude Code**: `claude mcp add --transport http emailmd https://www.emailmd.dev/api/mcp`
* **Claude.ai and Claude Desktop**: Customize → Connectors → Add (top right) → Add custom connector, then paste the URL above.
* **ChatGPT**: Settings → Apps & Connectors → Create (requires developer mode), then paste the URL above.
* **Cursor and VS Code**: use the one-click buttons, or add the server to your MCP config:

```json
{
  "mcpServers": {
    "emailmd": {
      "url": "https://www.emailmd.dev/api/mcp"
    }
  }
}
```

Run It Locally [#run-it-locally]

The same server ships inside the [CLI](/docs/cli) and runs over stdio, so rendering happens entirely on your machine:

```bash
npx emailmd mcp
```

For Claude Code:

```bash
claude mcp add emailmd -- npx emailmd mcp
```

The local server accepts the CLI's `--partials` flag, preloading [partials](/docs/partials) for every render and lint call:

```bash
npx emailmd mcp --partials ./partials
```

Tools [#tools]

| Tool        | What it does                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `render`    | Renders emailmd markdown and returns the complete HTML document, the plain-text MIME part, frontmatter metadata, render warnings, the output size in bytes, and a `previewUrl` |
| `lint`      | Runs [`lint()`](/docs/linting) and returns the findings with a summary, without rendering                                                                                      |
| `read_docs` | Fetches these docs from emailmd.dev, so the assistant can look up syntax it hasn't used before                                                                                 |

The `previewUrl` on every render is a [builder](/builder) share link. The markdown travels deflate-compressed in the URL fragment, so it never reaches the server; opening the link shows the email in a live preview with device switching and a dark-mode toggle.

The server also carries instructions that teach the assistant the emailmd workflow (write, lint, render, share the preview) and the syntax that goes beyond standard markdown, so even a client that never calls `read_docs` starts from a working baseline.

Versioning [#versioning]

The MCP server versions with the `emailmd` package: the hosted endpoint runs the latest release, and `npx emailmd mcp` runs whatever version is installed. Tool names and result shapes follow the same [stability policy](/docs/stability) as the API.


# Partials (/docs/partials)



Partials are named blocks of markdown you define once and reuse across emails: a legal footer, a branded header, a recurring promo card. The document references them with the `include` directive, and edits to a partial propagate to every email that includes it.

```markdown
# Your order has shipped

Track it from your account page.

::: include legal-footer
```

Partials are supplied to `render()` as a map of name → markdown string:

```typescript
import { render } from 'emailmd';

const { html } = await render(markdown, {
  partials: {
    'legal-footer': `::: footer
**Acme Inc.** · 123 Main St, Portland OR
[Unsubscribe]({{unsubscribe_url}}) · [Preferences]({{prefs_url}})
:::`,
  },
});
```

The same map works everywhere `RenderOptions` is accepted; pass it to the [builder](/docs/react)'s `renderOptions` prop and includes expand live in the preview.

There is no filesystem convention: emailmd also runs in the browser, so *where* partials live is up to your app. Server-side, loading them from a directory is a few lines:

```typescript
import { readFile, readdir } from 'node:fs/promises';
import path from 'node:path';

const dir = './emails/partials';
const partials = Object.fromEntries(
  await Promise.all(
    (await readdir(dir)).map(async (f) => [
      path.basename(f, '.md'),
      await readFile(path.join(dir, f), 'utf8'),
    ]),
  ),
);

const { html } = await render(markdown, { partials });
```

The [CLI](/docs/cli) has this built in: `emailmd input.md --partials ./partials` loads every `.md` file in the directory, with subdirectories as name prefixes (`blocks/legal.md` → `::: include blocks/legal`). The flag also accepts individual `.md` files (named by basename) and is repeatable, with later paths winning on name collisions.

Parameters [#parameters]

Pass parameters on the include line to fill `{{key}}` placeholders inside the partial. This is what turns an include into a reusable component. Values with spaces need quotes:

```markdown
::: include promo-card title="Summer sale" url="https://acme.com/sale"
```

```typescript
partials: {
  'promo-card': `::: callout
**{{title}}**

[Shop now]({{url}}){button}
:::`,
}
```

Only keys explicitly passed on the include line are substituted. Every other `{{token}}` passes through untouched for your app's template layer (Handlebars, Liquid, …) to resolve after render, following the same [pass-through contract](/docs/api-reference#renderoptions) as the rest of the pipeline. In the footer example above, `{{unsubscribe_url}}` survives into the output HTML exactly as written.

What a Partial Can Contain [#what-a-partial-can-contain]

Expansion happens textually before the markdown is parsed, so a partial can contain anything a document can: [directives](/docs/directives), [buttons](/docs/buttons), images, tables, even other includes. Nested includes expand up to 10 levels deep, and cycles are detected and skipped.

The one exception is frontmatter: a partial that starts with a `---` block gets it stripped with a warning. Frontmatter belongs on the document.

Partial names may contain letters, digits, `_`, `-`, `.`, and `/`, so a naming scheme like `blocks/legal` works if you want namespacing.

Errors Never Break the Render [#errors-never-break-the-render]

Consistent with the rest of emailmd, problems degrade with [warnings](/docs/api-reference#renderwarning) instead of throwing:

* An unknown partial name drops the include line and warns.
* A cycle (a partial including itself, directly or transitively) is skipped with a warning.
* Nesting deeper than 10 levels stops with a warning.

Include lines inside code fences and indented code blocks are left alone, so you can document the syntax itself in an email.

Partials vs. Snippets vs. Wrappers [#partials-vs-snippets-vs-wrappers]

* **Snippets** (in the [builder](/docs/react)) insert a *copy* at the cursor; later edits to the snippet don't affect emails already written.
* **Partials** are *live references*: edit the partial and every email that includes it changes on the next render.
* **[Wrappers](/docs/wrappers)** replace the whole document chrome in code, the right tool for layout-level control rather than content reuse.

Custom Pipelines [#custom-pipelines]

If you bypass `render()` and drive the pipeline yourself, the expansion pass is exported as `expandPartials(content, partials, warnings)`; call it on the frontmatter-stripped content before `parseMarkdown`.


# React Builder (/docs/react)



`@emailmd/react` packages the entire [emailmd.dev builder](/builder) as a drop-in component, plus the lower-level pieces (a render hook and a sandboxed preview) for building your own UI.

Install [#install]

```bash
npm install @emailmd/react emailmd
```

Requires React 18+. Rendering runs fully client-side (emailmd uses `mjml-browser` in the browser), so all components are client components.

<EmailmdBuilder /> [#emailmdbuilder-]

The full [emailmd.dev builder](/builder), as a drop-in component: CodeMirror markdown editor with a formatting toolbar, visual theme editor, emoji and snippet pickers, live preview with device switching and a dark-mode toggle (enabled when the email uses `theme: auto`), HTML source (pretty/minified with a Gmail-clip meter), plain-text view, render warnings, autosave, download, and optional share links. The builder page on this site is exactly this component.

```tsx
'use client';

import { EmailmdBuilder } from '@emailmd/react';
import '@emailmd/react/styles.css';

export function BuilderPage() {
  return <EmailmdBuilder />;
}
```

Give the parent element a height; the builder fills it.

| Prop                 | Type                              | Default          | Description                                                                               |
| -------------------- | --------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `defaultValue`       | `string`                          | starter template | Initial markdown when no draft or share link is present                                   |
| `value` / `onChange` | `string` / `(md: string) => void` | —                | Controlled mode (disables autosave)                                                       |
| `autoSave`           | `boolean \| string`               | `true`           | Draft persistence in localStorage; a string sets a custom key (default `"emailmd:draft"`) |
| `share`              | `boolean`                         | `false`          | Read `#md=` URL fragments on mount and show a share-link button                           |
| `colorScheme`        | `'light' \| 'dark'`               | `'light'`        | UI scheme                                                                                 |
| `renderOptions`      | `RenderOptions`                   | —                | Passed through to `render()` for the preview                                              |
| `lint`               | `boolean`                         | `false`          | Run [`lint()`](/docs/linting) on each render and surface findings in the warnings banner  |
| `debounceMs`         | `number`                          | `150`            | Typing → re-render debounce                                                               |
| `toolbarItems`       | `EmailmdBuilderToolbarItem[]`     | —                | Custom toolbar buttons; see below                                                         |
| `className`          | `string`                          | —                | Extra class on the root element                                                           |

Share links put the (deflate-compressed) document in the URL *fragment*, so shared markdown never reaches your server.

Custom Toolbar Buttons [#custom-toolbar-buttons]

Add your own buttons to the toolbar with `toolbarItems`. Each `onClick` receives the editor API, so a button can read and rewrite the document with no extra wiring. The classic use is an AI button:

```tsx
<EmailmdBuilder
  toolbarItems={[
    {
      id: 'ai',
      label: 'AI',
      tooltip: 'Draft with AI',
      onClick: async (editor) => {
        const prompt = window.prompt('What should this email say?');
        if (!prompt) return;
        const markdown = await draftEmail(prompt, editor.getMarkdown());
        editor.setMarkdown(markdown);
      },
    },
  ]}
/>
```

An item with an `icon` renders icon-only with its `label` as the accessible name and tooltip; without one, the label text renders on the button.

Driving the Editor [#driving-the-editor]

The same editor API is exposed through the component's ref, for driving the builder from outside the toolbar (a chat side panel, an import flow, a template picker):

```tsx
const builderRef = useRef<EmailmdBuilderHandle>(null);

<EmailmdBuilder ref={builderRef} />;

// Later, when your AI response arrives:
builderRef.current?.setMarkdown(generated);
```

| Method                   | What it does                                                   |
| ------------------------ | -------------------------------------------------------------- |
| `getMarkdown()`          | Returns the current document                                   |
| `setMarkdown(md)`        | Replaces the whole document                                    |
| `insertAtCursor(text)`   | Inserts at the cursor, leaving existing text in place          |
| `replaceSelection(text)` | Replaces the selected range (inserts at the cursor when empty) |
| `getSelection()`         | Returns `{ text, from, to }` for the current selection         |
| `focus()`                | Focuses the editor                                             |

Every mutation goes through a CodeMirror transaction, so autosave and `onChange` fire exactly as if the user had typed, and each call lands as a single undo step: your users can Cmd+Z away an AI draft they don't like. `getSelection` plus `replaceSelection` enable selection-scoped AI actions like "rewrite this paragraph".

Styling [#styling]

The UI has no Tailwind or component-library dependency. `styles.css` scopes everything under `.emd-` class names and derives all colors from `--emd-*` CSS custom properties, so you can retheme it:

```css
.emd-builder {
  --emd-link: #7c3aed;
  --emd-radius: 10px;
}
```

useEmailmd(markdown, options?) [#useemailmdmarkdown-options]

Renders markdown to email-safe HTML as it changes. Debounced, race-safe (stale renders never overwrite newer ones), and SSR-safe (returns empty output on the server).

```tsx
'use client';

import { useState } from 'react';
import { useEmailmd, EmailPreview } from '@emailmd/react';

export function Editor() {
  const [markdown, setMarkdown] = useState('# Hello');
  const { html, text, meta, warnings, error, isRendering } = useEmailmd(markdown);

  return (
    <div style={{ display: 'flex', height: '100%' }}>
      <textarea value={markdown} onChange={(e) => setMarkdown(e.target.value)} />
      <EmailPreview html={html} />
    </div>
  );
}
```

Options extend [`RenderOptions`](/docs/api-reference#renderoptions), so `theme`, `fonts`, `minify`, `strings`, and the rest all pass through, plus:

| Option       | Type      | Default | Description                                                                           |
| ------------ | --------- | ------- | ------------------------------------------------------------------------------------- |
| `debounceMs` | `number`  | `150`   | Wait after the last keystroke before re-rendering. `0` renders immediately.           |
| `lint`       | `boolean` | `false` | Run [`lint()`](/docs/linting) alongside each render; findings land in `lintFindings`. |

The returned object:

| Field          | Type              | Description                                                  |
| -------------- | ----------------- | ------------------------------------------------------------ |
| `html`         | `string`          | Complete email document (empty until the first render lands) |
| `text`         | `string`          | Plain-text MIME part                                         |
| `meta`         | `object`          | Frontmatter metadata                                         |
| `warnings`     | `RenderWarning[]` | Non-fatal issues; empty when clean                           |
| `lintFindings` | `LintFinding[]`   | Lint results when the `lint` option is on; empty otherwise   |
| `error`        | `Error \| null`   | Set if `render()` threw; previous output is retained         |
| `isRendering`  | `boolean`         | True while an updated render is in flight                    |

Options are compared by value, so inline object literals are fine. If you swap a custom `wrapper` *function* at runtime, memoize it; function identity changes aren't detected until the next input change.

<EmailPreview /> [#emailpreview-]

A sandboxed iframe showing a rendered email.

```tsx
<EmailPreview html={html} device="mobile" />
```

| Prop                 | Type                              | Default     | Description                                                                                                                                        |
| -------------------- | --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `html`               | `string`                          | —           | Rendered email document (`RenderResult.html`)                                                                                                      |
| `device`             | `'desktop' \| 'mobile' \| number` | `'desktop'` | `'desktop'` fills the container, `'mobile'` is 375px, or pass a pixel width                                                                        |
| `emulateColorScheme` | `'light' \| 'dark'`               | —           | Pin the preview to one of the email's [color-scheme variants](/docs/theme#automatic-dark-mode) regardless of the viewer's OS; unset follows the OS |

All other iframe props (`className`, `style`, `sandbox`, `title`, …) pass through.

The exported helper `hasDarkModeStyles(html)` tells you whether a rendered email opts into dark mode, useful for showing a dark-preview toggle only when it does something.

Versioning [#versioning]

`@emailmd/react` is versioned independently of `emailmd` and declares it as a peer dependency (`>=0.7.0`), so you control the rendering engine version.


# Stability & Versioning (/docs/stability)



emailmd follows [Semantic Versioning](https://semver.org/). This page defines what the version number makes promises about. The core idea:

> **The contract is the input language and the API, not the output bytes.**
> Your markdown keeps meaning the same thing; the exact HTML that expresses it may change.

Covered by Semver [#covered-by-semver]

Breaking any of these requires a **major** version bump:

The render() API [#the-render-api]

* The `render(markdown, options?)` signature and its `Promise<RenderResult>` return shape (`html`, `text`, `meta`, `warnings`).
* Every documented `RenderOptions` field and its accepted values.
* Existing [`RenderWarning`](/docs/api-reference#renderwarning) stages and the guarantee that warnings never turn into throws.

The input language [#the-input-language]

* Documented markdown behavior: headings, lists, tables, task lists, emoji shortcodes, inline HTML passthrough.
* Directive names and their documented parameters (`::: callout`, `bg=`, `center`, …).
* Button syntax: `{button}`, variants, `color`/`width`/`fallback`/`border-radius` attributes.
* Frontmatter keys: `preheader`, `theme`, the theme override keys, `fonts`, and the passthrough of custom keys into `meta`.
* Template tag passthrough (`{{ x }}`, `{% x %}`, `${x}`, `%%x%%`, `[[x]]`).

The rest of the public surface [#the-rest-of-the-public-surface]

* Exported functions and types: `buildHead`, `segmentsToMjml`, the theme objects and helpers, the sanitize helpers, `WrapperFn`/`WrapperMeta`, `Segment`.
* CLI arguments and flags, exit codes, and stdin/stdout behavior.
* Node.js version support (currently `>=20`); raising the floor is a major.

Rendering semantics [#rendering-semantics]

* What the output *means*: a callout renders as a visually distinct card, a primary button uses `buttonColor`, the preheader appears in the inbox preview, valid input never gains new warnings. Changes that alter how a documented feature *looks or behaves* in mainstream email clients are treated as breaking even if the API is untouched.

Not Covered by Semver [#not-covered-by-semver]

These may change in **minor or patch** releases:

* **Exact HTML output.** The generated markup structure, attribute order, whitespace, class names, and MJML-generated boilerplate. *Don't byte-snapshot the output in your tests.* Assert on content and semantics instead (e.g. "contains the button text and href"), the way [emailmd's own test suite](https://github.com/anypost/emailmd/tree/main/packages/emailmd/tests) does.
* **The bundled MJML version.** MJML minor/patch upgrades ship in emailmd minors or patches when output semantics are preserved.
* **Warning message text.** The `stage` and the *presence* of a warning for a given problem are stable; the human-readable `message` wording is not.
* **Internal formats.** The `<!--EMAILMD:...-->` marker namespace (reserved; user comments in it are dropped), template shielding placeholders, and the intermediate MJML document handed to `mjml2html`.
* **Undocumented behavior.** If it's not in these docs, it's an implementation detail, even if it happens to work today.

Additive Changes Land in Minors [#additive-changes-land-in-minors]

New capabilities that don't change existing behavior arrive in **minor** versions: new `RenderOptions` fields, new frontmatter keys, new directives or directive params, new warning stages, new exports, new theme keys (with defaults matching prior rendering), and new CLI flags. Code written against an older minor keeps working.

If you exhaustively match on union types like `RenderWarning['stage']` or `SegmentType`, include a default case; those unions grow in minors.

Deprecation Policy [#deprecation-policy]

Features are deprecated in a minor release (documented here and in the changelog, with a migration path) and removed no earlier than the next major.

Before 1.0 [#before-10]

Until 1.0, minor versions (0.x → 0.y) may include breaking changes; they are always called out in the [changelog](https://github.com/anypost/emailmd/blob/main/packages/emailmd/CHANGELOG.md) with migration notes. Patch releases are always safe. From 1.0 on, the full contract above applies.


# Tables (/docs/tables)



Standard GFM (GitHub Flavored Markdown) tables are supported and rendered as styled, email-safe HTML tables:

```markdown
| Name  | Role       | Status |
| ----- | ---------- | ------ |
| Alice | Engineer   | Active |
| Bob   | Designer   | Active |
| Carol | Manager    | Away   |
```

Column Alignment [#column-alignment]

Control column alignment using colons in the separator row: left-align with `:---`, center with `:---:`, right-align with `---:`:

```markdown
| Item                     |   Qty |    Price |
| :----------------------- | ----: | -------: |
| Monstera Deliciosa, 6"   |     1 |   $42.00 |
| Ceramic Pot, White       |     1 |   $18.00 |
| **Total**                |       | **$60.00** |
```

Headerless Tables [#headerless-tables]

Leave every cell in the header row empty and the row is dropped entirely: no bold header, no header border, just data rows:

```markdown
|          |          |
| :------- | :------- |
| Shipping | 3–5 days |
| Returns  | 30 days  |
```

The delimiter row is still required (that's what makes it a table in GFM), and column alignment set there still applies. This is a common markdown convention: in editors that don't support it, the table simply shows an empty header row instead of breaking.

Automatic Styling [#automatic-styling]

Tables are automatically styled with your theme colors:

* **Header row**: bold text with a 2px bottom border
* **Body rows**: subtle 1px bottom borders between rows
* **Cell padding**: consistent 8px vertical, 12px horizontal

All colors and borders inherit from your theme, so tables match the rest of your email without any extra configuration.

Tips [#tips]

Keep tables simple and narrow for the best results on mobile. Very wide tables may require horizontal scrolling on small screens, so stick to 2–4 columns when possible.


# Theme (/docs/theme)



Customize colors and fonts to match your brand:

```typescript
const { html } = await render(markdown, {
  theme: {
    brandColor: '#e11d48',
    buttonColor: '#e11d48',
    fontFamily: 'Georgia, serif',
  }
});
```

Dark Theme [#dark-theme]

A built-in dark theme is available. Pass it directly to render the email dark for everyone:

```typescript
import { render, darkTheme } from 'emailmd';

const { html } = await render(markdown, { theme: darkTheme });
```

Or use it as a base and override individual values:

```typescript
const { html } = await render(markdown, {
  theme: { ...darkTheme, brandColor: '#e11d48' },
});
```

You can also activate it per-email via frontmatter; see [Frontmatter](/docs/frontmatter).

Automatic Dark Mode [#automatic-dark-mode]

To render light by default but adapt to the reader's dark-mode preference, opt in with `darkTheme`:

```typescript
// Built-in dark palette
const { html } = await render(markdown, { darkTheme: true });

// Or override parts of it
const { html } = await render(markdown, {
  darkTheme: { brandColor: '#22d3ee' },
});
```

Or per-email in frontmatter with `theme: auto`:

```markdown
---
theme: auto
---
```

```markdown
---
theme: auto
dark:
  background_color: "#111827"
  content_color: "#1f2937"
---
```

The `dark:` map tunes the dark variant (and implies `auto` on its own). Explicitly pinning `theme: light` or `theme: dark` renders static even when the rendering app passes `darkTheme`: the author's pinned appearance wins.

This emits `color-scheme` meta tags, a `prefers-color-scheme: dark` media query, and `[data-ogsc]`/`[data-ogsb]` selectors for Outlook.com. **Client support varies:** Apple Mail and Outlook honor these overrides; Gmail ignores them and applies its own automatic color inversion regardless. Buttons keep their configured colors in both modes, so pick button colors that work on light and dark backgrounds.

Dark mode is palette-based: custom per-block colors (`bg=`/`color=` on callouts and columns, divider colors) are normalized to the dark palette so text stays readable. To tune how a specific accent looks in dark mode, adjust the corresponding key in the `dark:` map rather than the block parameter.

The overrides target stable `emd-*` CSS classes that emailmd emits on every render (`emd-root`, `emd-s`, `emd-bg`, `emd-card`, `emd-hl`, `emd-tbl`), which you can also target from a custom wrapper.

Web Fonts [#web-fonts]

To use a font beyond the web-safe stack (e.g. Google Fonts), pass a `fonts` map alongside `theme`. Each entry renders as an `<mj-font>` tag, loading the stylesheet in clients that support embedded web fonts:

```typescript
const { html } = await render(markdown, {
  fonts: {
    Inter: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap',
  },
  theme: {
    fontFamily: 'Inter, sans-serif',
  },
});
```

The font family still has to be named in `fontFamily` to actually apply; `fonts` only ships the stylesheet link. MJML drops unused entries automatically.

The same thing works from markdown with a nested `fonts:` map in frontmatter. See [Frontmatter → Custom Fonts](/docs/frontmatter#custom-fonts).

All Theme Options [#all-theme-options]

| Key                  | Light Default                                                                                                      | Dark Default | Description                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------- |
| `brandColor`         | `#18181b`                                                                                                          | `#fafafa`    | Links, highlights, accents                      |
| `headingColor`       | `#09090b`                                                                                                          | `#fafafa`    | Heading text                                    |
| `bodyColor`          | `#71717a`                                                                                                          | `#a1a1aa`    | Body text                                       |
| `backgroundColor`    | `#fafafa`                                                                                                          | `#09090b`    | Outer background                                |
| `contentColor`       | `#ffffff`                                                                                                          | `#18181b`    | Content area background                         |
| `cardColor`          | `#f4f4f5`                                                                                                          | `#27272a`    | Callout / code block background                 |
| `buttonColor`        | `#18181b`                                                                                                          | `#fafafa`    | Primary button background                       |
| `buttonTextColor`    | `#fafafa`                                                                                                          | `#18181b`    | Button text                                     |
| `secondaryColor`     | `#18181b`                                                                                                          | `#fafafa`    | Secondary button border                         |
| `secondaryTextColor` | `#18181b`                                                                                                          | `#fafafa`    | Secondary button text                           |
| `successColor`       | `#16a34a`                                                                                                          | *(same)*     | Success button background                       |
| `successTextColor`   | `#ffffff`                                                                                                          | *(same)*     | Success button text                             |
| `dangerColor`        | `#dc2626`                                                                                                          | *(same)*     | Danger button background                        |
| `dangerTextColor`    | `#ffffff`                                                                                                          | *(same)*     | Danger button text                              |
| `warningColor`       | `#d97706`                                                                                                          | *(same)*     | Warning button background                       |
| `warningTextColor`   | `#ffffff`                                                                                                          | *(same)*     | Warning button text                             |
| `dividerColor`       | `#f4f4f5`                                                                                                          | `#27272a`    | Horizontal rule (`---`) color                   |
| `fontFamily`         | `Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif` | *(same)*     | Font stack                                      |
| `fontSize`           | `16px`                                                                                                             | *(same)*     | Base font size                                  |
| `lineHeight`         | `1.6`                                                                                                              | *(same)*     | Base line height                                |
| `contentWidth`       | `600px`                                                                                                            | *(same)*     | Email width                                     |
| `borderRadius`       | `8px`                                                                                                              | *(same)*     | Border radius for buttons, callouts, highlights |

The dark theme inverts the color palette (light text on dark backgrounds) while keeping the same typography settings. You can import `darkTheme` directly or activate it per-email via [frontmatter](/docs/frontmatter).


# Wrappers (/docs/wrappers)



Most emails work great with the default wrapper: a gray outer background with a centered white content area. Custom wrappers are for when you need full control over the outer MJML structure, such as an edge-to-edge background color, custom `<mj-body>` attributes, or a multi-section layout.

Custom Wrapper [#custom-wrapper]

Supply a `WrapperFn` to replace the default outer structure:

```typescript
import { render, buildHead, segmentsToMjml } from 'emailmd';
import type { WrapperFn } from 'emailmd';

const myWrapper: WrapperFn = (segments, theme, meta) => {
  const head = buildHead(theme, meta?.preheader);
  const body = segmentsToMjml(segments, theme, {
    strings: meta?.strings,
    warnings: meta?.warnings,
  });
  return `<mjml>${head}<mj-body>${body}</mj-body></mjml>`;
};

await render(md, { wrapper: myWrapper });
```

The wrapper function receives three arguments:

* **`segments`**: the parsed content blocks from the markdown (text, buttons, images, directives, tables, etc.). Each segment has a `type`, `content`, and optional `attrs`.
* **`theme`**: the fully resolved theme object after merging defaults with any overrides from the render options and frontmatter.
* **`meta`**: the render context (`WrapperMeta`) with the `preheader`, the full `frontmatter` map including custom keys, plus `strings` and `warnings` to forward to `segmentsToMjml`.

Custom frontmatter keys are handy for wrapper-driven layouts:

```typescript
const myWrapper: WrapperFn = (segments, theme, meta) => {
  const banner = meta?.frontmatter?.campaign === 'summer-2026'
    ? '<mj-section><mj-column><mj-text>☀️ Summer Sale</mj-text></mj-column></mj-section>'
    : '';
  // ...
};
```

Helper Functions [#helper-functions]

emailmd exports two helpers for use inside custom wrappers:

* **`buildHead(theme, preheader?)`** generates the `<mj-head>` element containing global styles, font imports, and the hidden preheader text.
* **`segmentsToMjml(segments, theme, ctx?)`** converts the parsed segments into MJML body elements (sections, columns, text, buttons, images, tables, etc.).

You can call these helpers to reuse emailmd's rendering logic while customizing the outer shell, or you can skip them entirely and write raw MJML from scratch.

Forward `meta.strings` and `meta.warnings` into `segmentsToMjml`'s third argument (as in the example above) so localized strings apply and [content validation warnings](/docs/api-reference#input-validation) surface on the render result. Skipping them doesn't affect safety (invalid values still fall back to defaults); you just won't see the warnings.


# Accordion (/docs/directives/accordion)



An accordion turns headings into clickable, collapsible panels, ideal for FAQs. Each heading inside the block becomes a panel title, and the content below it becomes the panel body:

```markdown
::: accordion
### How do I reset my password?
Click **Forgot password** on the sign-in page.

### Where is my order?
Check the tracking link in your confirmation email.
:::
```

Any heading level works, and panel bodies support inline formatting, links, and lists. Text placed before the first heading renders as an intro paragraph above the accordion.

Client Support [#client-support]

Collapsing is interactive in WebKit-based clients (Apple Mail, iOS Mail) and some others. Clients without support (including Gmail and Outlook) show **every panel expanded**, which reads naturally: the fallback is just your headings and content in order. The plain-text version flattens the same way.

Custom Icons [#custom-icons]

By default the expand/collapse markers are `+` / `−` text glyphs colored with the theme's `heading_color`, so they stay visible on any background with no external images. To use your own icons instead, point `icon-wrapped` (collapsed state) and `icon-unwrapped` (expanded state) at self-hosted images:

```markdown
::: accordion icon-wrapped=https://cdn.example.com/plus.png icon-unwrapped=https://cdn.example.com/minus.png
### Question?
Answer.
:::
```

Notes [#notes]

* A block with no headings degrades to a regular text section and surfaces a render warning.
* Panel borders use the theme's `divider_color`, and titles use `heading_color`; both adapt in [dark mode](/docs/theme#automatic-dark-mode).


# Callout (/docs/directives/callout)



A callout renders a highlighted block, useful for tips, notes, or important information:

```markdown
::: callout
**Pro tip:** You can customize your dashboard in Settings.
:::
```

Callouts are styled with a subtle background color (using the theme's `cardColor`) to visually distinguish them from regular content.

Parameters [#parameters]

Add space-separated parameters after the directive name to customize appearance.

Alignment [#alignment]

```markdown
::: callout center
**ABC-123**
Your confirmation code.
:::
```

Supported values: `left` (default), `center`, `right`.

Padding [#padding]

```markdown
::: callout compact
Short note.
:::
```

Supported values: `compact` (`12px 16px`), `spacious` (`32px 40px`). The default padding is `20px 24px` when no keyword is provided.

Color & Background [#color--background]

Override the text color or background color with `color=` and `bg=`:

```markdown
::: callout color=#1e40af bg=#eff6ff
**Note:** Your account is pending review.
:::
```

Border Radius [#border-radius]

Override the default border radius (`8px`) with `border-radius=`:

```markdown
::: callout border-radius=16px
Rounder callout.
:::

::: callout border-radius=0
Sharp-cornered callout.
:::
```

Combined [#combined]

Parameters can be freely combined:

```markdown
::: callout center compact bg=#eff6ff
**ABC-123**
:::
```


# Centered (/docs/directives/centered)



A centered directive renders center-aligned text:

```markdown
::: centered
Thanks for reading.
The Acme Team
:::
```

Useful for sign-offs, short messages, or any content that looks better centered.

Color [#color]

Override the text color with a hex value:

```markdown
::: centered color=#00F7A4
Thanks for reading.
The Acme Team
:::
```

Other directives like [callout](/docs/directives/callout) and [highlight](/docs/directives/highlight) also support a `center` parameter for centering text within a styled block:

```markdown
::: callout center
**ABC-123**
:::
```


# Columns (/docs/directives/columns)



Columns place content side by side. The outer `columns` container uses four colons; each `column` inside uses three:

```markdown
:::: columns
::: column
![Product](https://picsum.photos/seed/product/600/400)
:::
::: column
**New in July**
Fresh features you'll love.
:::
::::
```

Columns are equal-width by default, render correctly in Outlook, and **stack vertically on mobile** automatically.

Inside a column you can use text, images, buttons, tables, dividers, and spacers; everything keeps its position within that column.

Column Parameters [#column-parameters]

Width [#width]

A bare number is a percentage; `width=` accepts a percent or pixel length:

```markdown
:::: columns
::: column 30
Narrow sidebar
:::
::: column 70
Main content
:::
::::
```

Alignment [#alignment]

`left` (default), `center`, `right` align the column's text, images, and buttons. `valign=` controls vertical alignment (`top`, `middle`, `bottom`) when columns have different heights:

```markdown
:::: columns
::: column center valign=middle
Centered, vertically middled
:::
::: column
Taller content...
:::
::::
```

Background [#background]

`bg=` gives a column a card-style background with inset padding (presets `compact`/`spacious` work like [callout](/docs/directives/callout)):

```markdown
:::: columns
::: column bg=#eff6ff compact
A card cell
:::
::: column
Plain cell
:::
::::
```

Text Color [#text-color]

`color=` overrides the text color for the column.

Container Parameters [#container-parameters]

Set on the outer `columns` container:

Gap [#gap]

Space between columns, in pixels (default `16`):

```markdown
:::: columns gap=32
...
::::
```

When columns stack on mobile, the gap between `bg` cards becomes vertical spacing. Use `gap=0` for flush cards.

Mobile Stacking [#mobile-stacking]

Columns stack on small screens by default. Keep them side by side with `stack=false`:

```markdown
:::: columns stack=false
::: column
🍎
:::
::: column
🍊
:::
::::
```

With `stack=false`, use percentage widths only.

Notes [#notes]

* Directives (callout, highlight, …) can't be nested inside columns; their content renders as regular text.
* In the plain-text version of the email, columns flatten to sequential content, left to right.


# Divider (/docs/directives/divider)



A plain markdown rule (`---`) renders as a subtle divider colored by the theme's `divider_color`. For a one-off styled rule, use the `divider` directive, a single line with no closing `:::`:

```markdown
Above.

::: divider color=#dc2626 thickness=2 width=50%

Below.
```

Parameters [#parameters]

| Parameter     | Syntax           | Description                                             |
| ------------- | ---------------- | ------------------------------------------------------- |
| **color**     | `color=<color>`  | Line color (default: theme `divider_color`)             |
| **thickness** | `thickness=<px>` | Line thickness (default `1px`; a bare number is pixels) |
| **width**     | `width=<length>` | Line width (default `100%`)                             |
| **align**     | Bare keyword     | `left`, `center`, `right`; position when width \< 100%  |

Theme default [#theme-default]

Set the default color for all `---` rules in frontmatter:

```markdown
---
divider_color: "#e2e8f0"
---
```

Dividers (both forms) read as `---` in the plain-text version of the email.


# Footer (/docs/directives/footer)



A footer renders at the bottom of the email with smaller, muted text:

```markdown
::: footer
**Acme Corp** · [Unsubscribe](https://example.com/unsub) · [Preferences](https://example.com/prefs)
:::
```

The footer is styled with reduced font size and muted colors, appropriate for legal text, unsubscribe links, and company information.

Parameters [#parameters]

Alignment [#alignment]

The footer is centered by default. Override with `left` or `right`:

```markdown
::: footer left
© 2026 Acme Corp · All rights reserved.
:::
```

Color [#color]

Override the text color with `color=`:

```markdown
::: footer color=#9ca3af
Legal text here.
:::
```


# Header (/docs/directives/header)



Content rendered above the main body area, typically a logo or brand image:

```markdown
::: header
![Logo](https://placehold.co/300x100.png?text=Logo){width="150"}
:::
```

The header appears at the very top of the email, before the main content area. It's commonly used for brand logos, navigation links, or a top banner.

Parameters [#parameters]

Alignment [#alignment]

The header is centered by default. Override with `left` or `right`:

```markdown
::: header left
![Logo](https://placehold.co/300x100.png?text=Logo){width="150"}
:::
```

Color [#color]

Override the text color with `color=`:

```markdown
::: header color=#1e40af
**Acme Corp**
:::
```


# Hero (/docs/directives/hero)



A full-width section with a background image and overlaid text, typically used as a hero banner at the top of an email:

```markdown
::: hero https://wsrv.nl/?url=picsum.photos/seed/hero/1200/600&filt=duotone&start=111827&stop=4b5563
# Welcome aboard
Get started with your new account today.
:::
```

The URL after `hero` specifies the background image. All content inside the directive is overlaid on top of it. (The `wsrv.nl` URLs in these examples are dark-filtered placeholder photos; see [Placeholder Images](/docs/images#placeholder-images).)

Text is centered and rendered in the theme's `button_text_color` (white in the default theme) for contrast against the background image.

Background Color Fallback [#background-color-fallback]

The hero always has a solid background color behind the image, defaulting to the theme's `button_color`. Many email clients block remote images until the reader opts in, so the fallback keeps the overlaid text readable; the theme's button color pair is already contrast-tested. Override it with `bg=`:

```markdown
::: hero https://wsrv.nl/?url=picsum.photos/seed/hero/1200/600&filt=duotone&start=111827&stop=4b5563 bg=#1f2937
# Welcome
Readable even before the image loads.
:::
```

The URL is optional: omit it and the hero renders as a solid banner. Hero colors are a self-contained pair, so dark mode leaves them alone: the section keeps its authored background and text colors in both modes. (Image-less heroes carry an `emd-hero-solid` class if you want to restyle them from custom wrapper CSS.)

```markdown
::: hero
# No image needed
A solid banner in the theme's button colors.
:::
```

Custom Text Color [#custom-text-color]

Override the text color with `color=`:

```markdown
::: hero https://wsrv.nl/?url=picsum.photos/seed/hero/1200/600&filt=duotone&start=111827&stop=4b5563 color=#ffffff
# Welcome
Some text over the image.
:::
```

This applies to all text inside the hero, including headings.

You can include any markdown content inside the hero: headings, paragraphs, buttons, and more:

```markdown
::: hero https://wsrv.nl/?url=picsum.photos/seed/sale/1200/600&filt=duotone&start=111827&stop=4b5563
# Summer Sale
Up to 50% off everything this weekend.

[Shop Now](https://example.com/sale){button color="#e11d48"}
:::
```

MJML handles Outlook VML fallbacks automatically, so the background image works across all major email clients.


# Highlight (/docs/directives/highlight)



A highlight renders an emphasized content block with a brand color accent:

```markdown
::: highlight
Limited time: first 100 signups get 50% off.
:::
```

The highlight directive uses the theme's `brandColor` to draw attention to important content like promotions, announcements, or key messages.

Parameters [#parameters]

Add space-separated parameters after the directive name to customize appearance.

Alignment [#alignment]

```markdown
::: highlight center
**50% OFF** this weekend only!
:::
```

Supported values: `left` (default), `center`, `right`.

Padding [#padding]

```markdown
::: highlight compact
Flash sale!
:::
```

Supported values: `compact` (`12px 16px`), `spacious` (`32px 40px`). The default padding is `20px 24px`.

Border Radius [#border-radius]

Override the default border radius (`8px`) with `border-radius=`:

```markdown
::: highlight border-radius=16px
Rounder highlight.
:::

::: highlight border-radius=0
Sharp-cornered highlight.
:::
```

Color & Background [#color--background]

Override the text color or background color with `color=` and `bg=`:

```markdown
::: highlight color=#ffffff bg=#dc2626
**URGENT:** Action required.
:::
```


# Directives (/docs/directives)



Directives are special block-level sections that control the email layout. They use the `:::` fenced container syntax:

```markdown
::: directive
Content goes here
:::
```

Available Directives [#available-directives]

| Directive                               | Description                                       |
| --------------------------------------- | ------------------------------------------------- |
| [header](/docs/directives/header)       | Content above the main body (logos, brand images) |
| [hero](/docs/directives/hero)           | Full-width section with background image          |
| [columns](/docs/directives/columns)     | Multi-column layouts that stack on mobile         |
| [callout](/docs/directives/callout)     | Highlighted tip or note                           |
| [highlight](/docs/directives/highlight) | Emphasized content block                          |
| [centered](/docs/directives/centered)   | Center-aligned text                               |
| [spacer](/docs/directives/spacer)       | Explicit vertical whitespace                      |
| [divider](/docs/directives/divider)     | Styled horizontal rule                            |
| [social](/docs/directives/social)       | Social link icon row                              |
| [accordion](/docs/directives/accordion) | Collapsible FAQ panels                            |
| [footer](/docs/directives/footer)       | Footer with links and legal text                  |

The `spacer` and `divider` directives are single-line: they take no content and need no closing `:::`.

There is also a single-line `include` directive that splices in reusable markdown [partials](/docs/partials) supplied by the rendering app.

Parameters [#parameters]

Some directives accept space-separated parameters after the directive name to customize alignment, padding, and colors:

```markdown
::: callout center
Centered callout content
:::

::: highlight center compact bg=#dc2626
Compact, centered highlight with custom background
:::
```

| Parameter         | Syntax                  | Values                                | Applies To                                   |
| ----------------- | ----------------------- | ------------------------------------- | -------------------------------------------- |
| **align**         | Bare keyword            | `center`, `left`, `right`             | callout, highlight, header, footer           |
| **padding**       | Bare keyword            | `compact`, `spacious`                 | callout, highlight                           |
| **color**         | `color=<color>`         | Hex, named, `rgb()`, or `hsl()` color | callout, highlight, centered, header, footer |
| **bg**            | `bg=<color>`            | Hex, named, `rgb()`, or `hsl()` color | callout, highlight                           |
| **border-radius** | `border-radius=<value>` | Any CSS length (e.g. `16px`, `0`)     | callout, highlight                           |

Parameter values are validated: an unrecognized color, alignment, or length falls back to the theme default and surfaces a [render warning](/docs/api-reference#renderwarning) rather than breaking the email. Template tags like `{{brand_color}}` are passed through for your sending app to resolve.

See each directive's page for detailed examples.


# Social (/docs/directives/social)



A social block turns a list of links into an icon row. The icon is derived from each link's hostname:

```markdown
::: social
- [GitHub](https://github.com/anypost/emailmd)
- [X](https://x.com/emailmd)
- [LinkedIn](https://www.linkedin.com/company/emailmd)
:::
```

Recognized networks: Facebook, X/Twitter, Instagram, LinkedIn, GitHub, YouTube, Pinterest, Medium, Vimeo, Dribbble, SoundCloud, Tumblr, Snapchat, and Xing. Any other host gets a generic web icon.

Parameters [#parameters]

Labels [#labels]

Icons only by default; add the `labels` flag to show each link's text next to its icon:

```markdown
::: social labels
- [Follow us](https://x.com/emailmd)
:::
```

Icon size and alignment [#icon-size-and-alignment]

```markdown
::: social icon-size=32 left
- [GitHub](https://github.com/anypost/emailmd)
:::
```

`icon-size` is pixels (default `24`). Alignment keywords: `left`, `center` (default), `right`.

Self-hosted icons [#self-hosted-icons]

The default icons are the MJML set, served from Mailjet's CDN. For production email we recommend hosting your own: point `icon-base` at a directory containing `<network>.png` files (e.g. `github.png`, `x.png`, `web.png`):

```markdown
::: social icon-base=https://cdn.example.com/icons/
- [GitHub](https://github.com/anypost/emailmd)
:::
```

You can also override a single link's icon with an attribute:

```markdown
::: social
- [Blog](https://blog.example.com){icon=https://cdn.example.com/blog.png}
:::
```

In the plain-text version of the email, the block flattens to `Label (url)` lines.


# Spacer (/docs/directives/spacer)



A spacer adds explicit vertical space between blocks. It's a single line; no closing `:::` needed:

```markdown
Above the gap.

::: spacer 48

Below the gap.
```

The number is the height in pixels; other CSS units work too (`::: spacer 2em`). Without a value the spacer is `24px`:

```markdown
::: spacer
```

Spacers work inside [columns](/docs/directives/columns) as well:

```markdown
:::: columns
::: column
Top of the column

::: spacer 40

Pushed down
:::
::: column
Other column
:::
::::
```

Spacers leave no trace in the plain-text version of the email.