Converting Markdown to HTML Email Without Breaking the Design
· 6 min read
Converting Markdown to HTML email means parse, then adapt: inline the styles, build layout with tables, and add the head boilerplate clients need.

Markdown to email looks like a solved problem and is not one. You write a readable source, convert it, and the result works in a browser and fails in the only place it matters. Tables collapse. Styles vanish. The layout breaks the moment a client strips a <style> block that the browser was relying on.
The cause is that email is not the web. It is a rendering environment with roughly two decades of accumulated client-specific behavior, most of it documented in fragments. A converter can do the Markdown part well, and the Markdown to HTML pipeline that produces it is well specified. What it cannot do is bridge the gap between a stylesheet and a client that may not read stylesheets at all.
Key Takeaways
- Email clients vary far more than browsers, and the differences are in layout, not in Markdown parsing.
- A
<style>block in the head is unreliable; styles inlined on each element are the dependable approach.- Tables are the layout primitive in email, not a content choice, because flexbox and grid are not dependable.
- Convert the Markdown, then inline the CSS, then test in real clients. Skipping either step loses the design.
What Is Markdown to HTML Email?
It is a two-stage pipeline that people usually treat as one. The first stage is familiar: parse the Markdown, produce HTML. The second stage is email-specific, and it is the one that decides whether the result looks right.
The Markdown to HTML converter handles the first stage, and it is the easy half. The second stage takes that HTML and adapts it to an email rendering environment, which means inlining styles, converting the layout to tables, and adding the boilerplate a client expects in the head.
The HTML specification defines what valid markup is, and an email document that is valid HTML can still fail to render. The distinction matters because a failure in stage one is obvious, while a failure in stage two is invisible until you look at the actual rendered message. The HTML is valid in both cases.
Why email is not the web
A browser is a reasonably uniform rendering environment. Email clients are documented one at a time, and the Can I Email support tables are the reference that consolidates them, covering every major client feature by feature. Email clients are not, and the differences are structural rather than cosmetic.
The Can I Email project tracks support across major clients, feature by feature, and its data explains most of the constraints below. The important ones for a converter are that many clients do not reliably support <style> blocks in the head, that flexbox and grid have patchy or absent support, and that image blocking is on by default in several clients, so a design that depends on a background image may show nothing at all.
Support varies by client and by feature, which is what the Can I Email feature index tabulates. This is why an email that renders perfectly in a browser can arrive as unstyled text. The browser applied a stylesheet the client discarded, and the fallback was unstyled.
The same tables cover the specific quirks worth knowing before you design: which clients clip a message that exceeds a size threshold, and which restrict CSS support in ways that silently drop a rule.
Inline the styles, do not rely on a stylesheet
The single most consequential habit in email HTML is putting style rules on the elements themselves.
<!-- unreliable -->
<style>
.button { background: #2563eb; color: #fff; }
</style>
<a href="#" class="button">Click</a>
<!-- dependable -->
<a href="#" style="background:#2563eb;color:#fff;padding:12px 20px;">Click</a>
The second version renders the same everywhere. The first renders correctly in clients that honor head styles and falls back to plain text in the ones that do not, which is a failure the recipient sees and the sender never does.
The cost of inlining is verbosity, and that verbosity is the reason the step belongs in a build rather than in the source file. Generated HTML with inlined styles is larger and harder to read, which is why a build step that inlines a stylesheet is worth having even when the source is written with a <style> block. Most email build pipelines include a step for this, and it is worth having even when the source is written with a <style> block, because the source stays readable while the output stays reliable.
Build layout with tables
This is the part that feels dated and is still correct. Flexbox and grid have incomplete support across email clients, and a layout that depends on them will collapse in a meaningful share of real inboxes. The Can I Email support tables record the per-client picture. Tables, by contrast, have worked in email clients since the beginning and are the reason so many email templates look the way they do.
The consequence is that an email is usually a table at the outer level, with nested tables for columns, and the Markdown source describes content rather than layout. If your Markdown is a document with headings, lists, and prose, you will need to decide where the single-column table wrapper goes. Most tools put one around the whole message.
This is the biggest structural difference between email HTML and web HTML, and it is why a converter aimed at email is not simply a web converter with different CSS. What it needs to do is wrap content in layout that the client will honor.
The head boilerplate
An email document needs a specific set of things in the head that a web page does not. The minimum that works reliably:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Message subject</title>
</head>
<body>
<!-- preheader text -->
<div style="display:none;max-height:0;overflow:hidden;">Preview text</div>
<!-- content -->
</body>
</html>
Two of these are worth explaining. The viewport meta is what makes a message scale on a phone, and without it a mobile client renders a desktop-width layout squeezed into a narrow column. The preheader div is the grey text most clients show next to the subject line in an inbox; clients generate one from whatever text comes first, so an explicit hidden line is how you control it.
The viewport meta and the preheader are the two that materially change what a recipient sees. The X-UA-Compatible line is a holdover for older Internet Explorer, which some corporate environments still route mail through. It costs nothing.
Images, and the blocking problem
Several clients block remote images by default, showing a placeholder until the recipient allows them. A design whose message is carried by an image therefore arrives as an empty box.
The fix is to make the text carry the meaning and use images for what text cannot do. Keep the headline, the offer, and the call to action as text. Use images for anything genuinely visual, and always set meaningful alt text, because that is what the recipient sees when images are blocked.
The Markdown syntax cheat sheet covers image syntax, and the alt text is the part that matters here rather than the URL. Related tools that help: the HTML to PDF converter for producing a static version, and the HTML CSS live preview for checking the layout before it goes out.
A workable workflow
Four steps, in order, and the order matters.
- Write in Markdown, keeping layout out of it. Headings, lists, links, images, and tables carry the content.
- Convert to HTML, sanitizing the result. A converter should never emit unsanitized markup, and email is a context where that matters as much as the web.
- Inline the styles and wrap the content in the table layout, adding the head boilerplate.
- Test in real clients. This is the step that catches what the other three cannot, and it is covered in how to test HTML email rendering, which covers client testing in detail rather than the conversion step.
The CommonMark specification defines the source syntax that stage one parses, and DOMPurify is the sanitizer that stage two should use. Steps one through three are deterministic and belong in a build. Step four is empirical and needs a real inbox. Skipping it is how a template that works on your machine reaches a list of several thousand people.
Related tools and further reading
The Markdown to HTML converter handles step two, rendering and sanitizing in your browser with nothing uploaded. Step three is where a dedicated email tool earns its place, because the table wrapper and style inlining are email-specific rather than general HTML concerns. For the rendering side, how to test HTML email rendering before you hit send covers which clients matter and what to look for. The HTML Entity Encoder/Decoder helps when a subject line or snippet needs escaped characters, and the Markdown syntax cheat sheet covers the source syntax, particularly images and tables.

Written by
Callum Reid
Markdown is a family of closely related dialects, and most bugs in it come from writing for one and rendering in another. On top of that sit tables, footnotes, task lists, strikethrough, attributes, maths and raw HTML. A renderer either enables a subset of these or ignores them silently, and ignored syntax usually surfaces as literal punctuation.
Fenced code blocks are the most reliable part and still have edge cases. Info strings carry a language identifier for highlighting, and some renderers read options from the same string. An unclosed fence swallows the remainder of the document, which is why a stray backtick is worth checking first when a page renders short.
Links get their own treatment. Reference-style links resolve anywhere in the document, which is convenient right up until two definitions collide. Bare URLs are autolinked by some renderers and left as plain text by others, and a link with mismatched brackets produces output that looks fine and points at the wrong place. Raw HTML is where sanitisation earns its place.
Markdown passes HTML through by design, so a document containing a script tag or an event handler attribute reaches the browser unless the pipeline strips it. Sanitisers differ in which tags they allow, and allowing a tag for a benign reason can permit an attribute with a script handler, reintroducing the problem it was meant to remove. I cover heading level discipline too, because renderers frequently promote or demote headings to fit a template, and that silently breaks both the outline and accessibility.