Markdown to Email HTML
Convert markdown into a complete, self-contained HTML email with inline CSS, table-based layout, and cross-client compatibility (Gmail, Outlook, Apple Mail).
Workflow
1. Determine input
- If the user provided a file path, read the
.md file
- If the user provided inline markdown, use that directly
- If neither, ask: "Which markdown file should I convert, or paste the content?"
2. Parse frontmatter
Extract YAML frontmatter from the top of the markdown. All fields are optional — use defaults for anything missing.
| Field |
Default |
Description |
preheader |
(none) |
Hidden inbox preview text |
brand-color |
#2563eb |
Primary accent (links, buttons, highlights) |
heading-color |
#1a1a1a |
h1-h3 color |
body-color |
#333333 |
Body text color |
background-color |
#f4f4f4 |
Outer background |
content-background |
#ffffff |
Inner content area |
font-family |
Arial, Helvetica, sans-serif |
Safe font stack |
font-size |
16px |
Base body size |
line-height |
26px |
Body line height (must be px for Outlook) |
content-width |
600px |
Max content width |
header-logo |
(none) |
URL to logo image |
footer-text |
(none) |
Footer text (unsubscribe, address, etc.) |
3. Load references
Read the following files for technical rules and component templates:
references/email-html-compatibility.md — cross-client rules, document structure, quirksreferences/email-components.md — HTML snippets with {{variable}} placeholders
4. Convert markdown to email HTML
Walk through the markdown content and generate email-safe HTML:
- Use the Complete Wrapper template as the outer structure
- Map each markdown element to its corresponding component template
- Replace all
{{variable}} placeholders with frontmatter values (or defaults)
- Apply all CSS inline — no
<style> blocks in <body>
- Use tables for layout — never
<div> for structure
- Include Outlook conditional comments for
max-width fix
- Include preheader
<div> if preheader is set
- Include header with logo if
header-logo is set
- Include footer if
footer-text is set
Markdown element mapping:
| Markdown |
Email component |
# Heading |
Heading (h1-h4) with size per level |
| Paragraph |
Paragraph with inline styles |
**bold**, *italic*, ~~strike~~ |
Inline <strong>, <em>, <del> |
[text](url) |
Styled <a> with brand-color |
- item / 1. item |
Unordered/Ordered list |
- [ ] task |
Task list with Unicode checkboxes |
`code` |
Inline code |
```code block``` |
Code block (dark theme) |
> quote |
Blockquote with left border |
 |
Image with explicit dimensions |
--- |
Horizontal rule |
==highlight== |
<mark> with background color |
Special directives (fenced with :::):
| Directive |
Behavior |
:::hero |
Full-width section with brand-color background, white text |
:::callout[type] |
Highlighted box — type: info, tip, warning, danger |
:::button[text](url) |
CTA button with VML fallback |
:::button.secondary[text](url) |
Secondary button variant |
:::centered |
Center-aligned text block |
:::footer |
Footer section (overrides footer-text frontmatter) |
5. Write output
- If input was a file (e.g.,
newsletter.md), write to newsletter.html in the same directory
- If input was inline, ask the user for an output path
- The output must be a complete, self-contained HTML document — ready to paste into any email sending tool
6. Summary
Report:
- Output file path
- Theme values applied (brand color, font, content width)
- Any warnings (e.g., unsupported markdown features skipped, images without dimensions)
Constraints
- No
<style> in <body> — Gmail strips it. Only allowed in <head> for responsive media queries.
- No flexbox, grid, or CSS variables — not supported in email clients
- No
<button> elements — use <a> tags styled as buttons
- No JavaScript — always blocked
- No external CSS — everything inline
- Tables for layout —
<div> only for non-structural content (e.g., preheader hiding)
- px units only — no
rem, em, vh, vw, or calc()
- Explicit dimensions on images — always set
width and height
- Absolute URLs — all
src and href must be fully qualified
Example Input
---
preheader: "Your weekly update is here"
brand-color: "#6366f1"
header-logo: "https://example.com/logo.png"
footer-text: "Acme Inc. | 123 Main St | [Unsubscribe](https://example.com/unsub)"
---
:::hero
# Welcome to the Weekly Update
Everything you need to know, in one email.
:::
## What's New
We shipped **three major features** this week:
- Real-time collaboration
- Dark mode support
- Export to PDF
:::callout[tip]
Try dark mode by going to Settings > Appearance.
:::
:::button[Try it now](https://example.com/app)
## By the Numbers
| Metric | This Week | Last Week |
|---|---|---|
| Active Users | 12,450 | 11,200 |
| Signups | 890 | 720 |
> "This is the best update yet!" — A happy user
---
Thanks for reading. See you next week!
1---2name: cmd-email-md3description: Convert markdown to email-safe HTML with inline styles and cross-client compatibility. Use when writing newsletters, transactional emails, or any HTML email from markdown source.4---56# Markdown to Email HTML78Convert markdown into a complete, self-contained HTML email with inline CSS, table-based layout, and cross-client compatibility (Gmail, Outlook, Apple Mail).910## Workflow1112### 1. Determine input1314- If the user provided a file path, read the `.md` file15- If the user provided inline markdown, use that directly16- If neither, ask: "Which markdown file should I convert, or paste the content?"1718### 2. Parse frontmatter1920Extract YAML frontmatter from the top of the markdown. All fields are optional — use defaults for anything missing.2122| Field | Default | Description |23|---|---|---|24| `preheader` | (none) | Hidden inbox preview text |25| `brand-color` | `#2563eb` | Primary accent (links, buttons, highlights) |26| `heading-color` | `#1a1a1a` | h1-h3 color |27| `body-color` | `#333333` | Body text color |28| `background-color` | `#f4f4f4` | Outer background |29| `content-background` | `#ffffff` | Inner content area |30| `font-family` | `Arial, Helvetica, sans-serif` | Safe font stack |31| `font-size` | `16px` | Base body size |32| `line-height` | `26px` | Body line height (must be px for Outlook) |33| `content-width` | `600px` | Max content width |34| `header-logo` | (none) | URL to logo image |35| `footer-text` | (none) | Footer text (unsubscribe, address, etc.) |3637### 3. Load references3839Read the following files for technical rules and component templates:4041- `references/email-html-compatibility.md` — cross-client rules, document structure, quirks42- `references/email-components.md` — HTML snippets with `{{variable}}` placeholders4344### 4. Convert markdown to email HTML4546Walk through the markdown content and generate email-safe HTML:4748- Use the **Complete Wrapper** template as the outer structure49- Map each markdown element to its corresponding component template50- Replace all `{{variable}}` placeholders with frontmatter values (or defaults)51- Apply **all CSS inline** — no `<style>` blocks in `<body>`52- Use **tables for layout** — never `<div>` for structure53- Include Outlook conditional comments for `max-width` fix54- Include preheader `<div>` if `preheader` is set55- Include header with logo if `header-logo` is set56- Include footer if `footer-text` is set5758**Markdown element mapping:**5960| Markdown | Email component |61|---|---|62| `# Heading` | Heading (h1-h4) with size per level |63| Paragraph | Paragraph with inline styles |64| `**bold**`, `*italic*`, `~~strike~~` | Inline `<strong>`, `<em>`, `<del>` |65| `[text](url)` | Styled `<a>` with brand-color |66| `- item` / `1. item` | Unordered/Ordered list |67| `- [ ] task` | Task list with Unicode checkboxes |68| `` `code` `` | Inline code |69| ` ```code block``` ` | Code block (dark theme) |70| `> quote` | Blockquote with left border |71| `` | Image with explicit dimensions |72| `---` | Horizontal rule |73| `==highlight==` | `<mark>` with background color |7475**Special directives** (fenced with `:::`):7677| Directive | Behavior |78|---|---|79| `:::hero` | Full-width section with brand-color background, white text |80| `:::callout[type]` | Highlighted box — type: `info`, `tip`, `warning`, `danger` |81| `:::button[text](url)` | CTA button with VML fallback |82| `:::button.secondary[text](url)` | Secondary button variant |83| `:::centered` | Center-aligned text block |84| `:::footer` | Footer section (overrides `footer-text` frontmatter) |8586### 5. Write output8788- If input was a file (e.g., `newsletter.md`), write to `newsletter.html` in the same directory89- If input was inline, ask the user for an output path90- The output must be a complete, self-contained HTML document — ready to paste into any email sending tool9192### 6. Summary9394Report:95- Output file path96- Theme values applied (brand color, font, content width)97- Any warnings (e.g., unsupported markdown features skipped, images without dimensions)9899## Constraints100101- **No `<style>` in `<body>`** — Gmail strips it. Only allowed in `<head>` for responsive media queries.102- **No flexbox, grid, or CSS variables** — not supported in email clients103- **No `<button>` elements** — use `<a>` tags styled as buttons104- **No JavaScript** — always blocked105- **No external CSS** — everything inline106- **Tables for layout** — `<div>` only for non-structural content (e.g., preheader hiding)107- **px units only** — no `rem`, `em`, `vh`, `vw`, or `calc()`108- **Explicit dimensions on images** — always set `width` and `height`109- **Absolute URLs** — all `src` and `href` must be fully qualified110111## Example Input112113```markdown114---115preheader: "Your weekly update is here"116brand-color: "#6366f1"117header-logo: "https://example.com/logo.png"118footer-text: "Acme Inc. | 123 Main St | [Unsubscribe](https://example.com/unsub)"119---120121:::hero122# Welcome to the Weekly Update123Everything you need to know, in one email.124:::125126## What's New127128We shipped **three major features** this week:129130- Real-time collaboration131- Dark mode support132- Export to PDF133134:::callout[tip]135Try dark mode by going to Settings > Appearance.136:::137138:::button[Try it now](https://example.com/app)139140## By the Numbers141142| Metric | This Week | Last Week |143|---|---|---|144| Active Users | 12,450 | 11,200 |145| Signups | 890 | 720 |146147> "This is the best update yet!" — A happy user148149---150151Thanks for reading. See you next week!152```
olshansk