Markdown and email
How to convert Markdown into email-safe HTML
Write a clean Markdown source, convert it to conservative HTML, inline essential styles, and test links, images, accessibility, and client rendering.
Document summary
A practical workflow for producing email HTML from Markdown without assuming that browser CSS and modern layout features will work in every inbox.
Key takeaways
- Email clients support a narrower HTML and CSS environment than browsers.
- Use simple structure, inline essential styles, and absolute links.
- Test the final message in representative clients before sending.
Design for the email environment
Email HTML is rendered by many different engines with inconsistent CSS support. Scripts, forms, embedded applications, and advanced layouts are commonly removed or blocked.
Treat Markdown as a clean authoring source, then convert it into a conservative, self-contained email document.
Keep the Markdown source simple and semantic
Use headings, paragraphs, lists, links, images, and simple tables. Avoid deeply nested lists, large code blocks, and embedded HTML unless the sending platform explicitly supports them.
- Use a clear heading hierarchy.
- Keep paragraphs short for narrow screens.
- Use descriptive link text.
- Provide image alternative text.
- Include a plain-text version of the message.
Inline essential styles
Many email workflows inline CSS so important typography, spacing, colors, and table rules travel with each element. Keep decorative CSS optional and make the message understandable without it.
| Need | Safer approach | Avoid relying on |
|---|---|---|
| Layout | Simple tables or single-column flow | Complex grid or application-style layouts |
| Spacing | Inline padding and margins with testing | Global style inheritance alone |
| Fonts | System font stack with fallback | Remote fonts as the only option |
| Buttons | Styled links with readable text | JavaScript actions |
| Responsive behavior | Fluid widths and tested media queries | Desktop-only fixed widths |
Use absolute links and reliable images
Email recipients open messages outside your website, so relative URLs do not resolve reliably. Use complete HTTPS links for pages and hosted images.
Assume images may be blocked. The message, call to action, and key information should remain understandable from text alone.
[View report](/reports/42)
[View the report](https://example.com/reports/42)
Review accessibility and dark-mode behavior
Use sufficient contrast, meaningful headings, descriptive links, and alternative text. Do not place essential text only inside an image.
Some clients adjust colors in dark mode. Test brand colors, backgrounds, logos, borders, and button text with automatic dark-mode transformations.
Test the final sent message
- 1
Preview desktop and narrow mobile widths.
- 2
Send a test through the real email platform.
- 3
Open it in representative webmail, desktop, and mobile clients.
- 4
Check links, images, tracking parameters, and unsubscribe content.
- 5
Review the plain-text alternative.
- 6
Verify that copying and forwarding still preserves meaning.
