ToolBoxes

Converting Markdown to Email HTML: A Practical Guide

May 28, 20266 min read

Email HTML Is Not Web HTML

Web browsers render standards-compliant HTML consistently. Email clients do not. Gmail strips <style> blocks, Outlook uses Microsoft Word for rendering, and mobile clients impose their own constraints. When you convert Markdown to HTML for email, you must account for these limitations.

The conversion itself is straightforward. Making the output render reliably across 50+ email clients is the real challenge.

The Conversion Pipeline

Step 1: Markdown to Standard HTML

Use a Markdown parser to produce clean HTML. Most parsers generate semantic markup that works fine for web but needs adjustment for email.

const { marked } = require('marked');

const markdown = `
# Welcome to Our Newsletter

This week we cover:

- New feature release
- Performance improvements
- Upcoming events

## Feature Release

The **dashboard** now supports custom widgets. [Learn more](https://example.com/features).
`;

const html = marked.parse(markdown);

Step 2: Inline All Styles

Email clients like Gmail remove <style> blocks from the <head>. Every CSS property must be inlined on each element.

const juice = require('juice');

const styledHtml = `
<html>
<head>
<style>
  h1 { color: #1a1a1a; font-size: 24px; font-family: Arial, sans-serif; }
  p { color: #333333; font-size: 16px; line-height: 1.5; }
  a { color: #0066cc; text-decoration: underline; }
  ul { padding-left: 20px; }
  li { margin-bottom: 8px; }
</style>
</head>
<body>
  ${html}
</body>
</html>
`;

const inlinedHtml = juice(styledHtml);
// All styles are now inline on each element

handling Markdown Elements for Email

Headings

Avoid <h1> tags in email — some clients override heading styles unpredictably. Use styled <p> or <div> tags instead.

<!-- Instead of <h1> -->
<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td style="font-family: Arial, sans-serif; font-size: 24px; font-weight: bold; color: #1a1a1a; padding-bottom: 16px;">
      Welcome to Our Newsletter
    </td>
  </tr>
</table>

Lists

Unordered and ordered lists render inconsistently across clients. Convert them to table-based layouts for reliable indentation and bullet display.

<!-- Instead of <ul><li> -->
<table cellpadding="0" cellspacing="0">
  <tr>
    <td style="font-family: Arial, sans-serif; font-size: 16px; color: #333333; padding-bottom: 8px;">
      • New feature release
    </td>
  </tr>
  <tr>
    <td style="font-family: Arial, sans-serif; font-size: 16px; color: #333333; padding-bottom: 8px;">
      • Performance improvements
    </td>
  </tr>
</table>

Always use absolute URLs and include both color and underline styles inline:

<a href="https://example.com/features" style="color: #0066cc; text-decoration: underline;">Learn more</a>

Code Blocks

Code blocks are particularly tricky. Most Markdown parsers wrap code in <pre><code> tags, which many email clients render poorly or not at all.

<!-- Email-safe code block -->
<table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f5f5f5; border-radius: 4px;">
  <tr>
    <td style="font-family: 'Courier New', monospace; font-size: 14px; color: #333333; padding: 16px; white-space: pre-wrap; word-break: break-all;">
npm install @example/sdk
    </td>
  </tr>
</table>

Layout Structure

Email layouts should use nested tables with explicit widths. CSS Flexbox and Grid are not supported in many email clients.

<table width="100%" cellpadding="0" cellspacing="0" style="background-color: #ffffff;">
  <tr>
    <td align="center" style="padding: 20px;">
      <table width="600" cellpadding="0" cellspacing="0" style="max-width: 600px;">
        <tr>
          <td style="font-family: Arial, sans-serif; font-size: 16px; color: #333333; line-height: 1.5;">
            <!-- Email content here -->
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>

Outlook-Specific Fixes

Outlook for Windows uses Word's HTML rendering engine, which lacks support for many CSS properties:

CSS PropertyOutlook SupportWorkaround
max-widthNoUse <table width="600">
padding on <div>PartialUse padding on <td>
background-imageNoUse <img> with absolute URL
border-radiusNoAccept square corners or VML
marginPartialUse cellpadding and cellspacing

Testing Workflow

  1. Convert Markdown to HTML with your parser
  2. Inline all CSS styles
  3. Wrap content in table-based email layout
  4. Test with email preview tools (Litmus, Email on Acid)
  5. Send a test to yourself across Gmail, Outlook, and Apple Mail

Key Takeaways

  • Email HTML requires inline styles — <style> blocks get stripped by major clients
  • Use table-based layouts instead of Flexbox or Grid
  • Convert Markdown lists and headings to table rows for reliable rendering
  • Code blocks need monospace fonts and white-space: pre-wrap for email
  • Outlook for Windows is the most problematic client — test early and often
  • Always use absolute URLs for links and images in email

Try It Yourself

Convert Markdown to clean HTML instantly with our free Markdown to HTML Converter. Paste any Markdown text to get properly formatted HTML output — all processing happens locally in your browser.

Try the Markdown to HTML Converter →