Why it is hard to generate beautiful HTML emails (from Markdown)
Developer-centric products often want to send newsletter with embedded code snippets. Some of them already write their documentation in Markdown. Why not write the newsletter in Markdown too and turn it into nicely formatted HTML email...!?
This idea sounds quite nice and it doesn't seem to be only a theoretical problem. On Twitter, Adam describes a cumbersome workflow that he employs now. I suspect that a "one click" solution would be worth some of his money spent.
Markdown email isn't something off this world still it has some gotchas we're going to talk about in this article.
Let's talk about how such a nerdy newsletter product could possibly look like. I'm going to give this tool the pseudonym "Mailchimp for nerds" for this article. Sometimes I just call it "our tool".
How to send your first newsletter?
Hopefully that's the simplest solution we can come up with and still solves the real problem Adam has.
Your journey
Write the newsletter in your favorite editor, all plain text in Markdown. Open the browser, sign into our "Mailchimp for nerds". It shows a text area where you paste the markdown you've just written. When done hit the "Send Test" button. It sends the newsletter to you so you can review how it looks like. It's a poor man's preview but works. When you're happy then hit the "Send" button and the newsletter is out to your mailing list.
Keep your existing mailing list
Where does the mailing come from? Instead of managing it inside our tool it's better to use existing tools and use it via their API. Mailchimp can be the first supported one. Or any other widely-adopted one, we just need to pick one for the MVP.
Templates
Our tool also needs to generate the email from Markdown. Therefore we need a template.
Styling HTML-based emails was a nightmare. It's the 1990s-approach in web design with tables and inline styles because of the vast amount of different mail clients and their old render engines. Each one understands and renders HTML and CSS differently. Sounds like IE times. It (hopefully) got better with the proliferation of mail clients like GMail.
Again, like with the mailing list, our tool doesn't manage the templates. You select one that you already have in your previous tool like Mailchimp. We connect through the API.
Inline images
Use standard Markdown inline image links which can point wherever you store your images. "Mailchimp for nerds" fetches, resizes, and embeds them directly into the email. External links stay external as their name suggests.
Your brand's addresses
"Mailchimp for nerds" adds From and Reply-To addresses with your own domain. Nothing sucks more than a domain that isn't yours but from the tool provider!
Technical details
HTML + Plain text
Some email clients don't support HTML versions or people just prefer plain text so it got practice to send both plain text and HTML versions to account for this fact. Suppossingly multipart newsletters also score lower on the spam rank which is a good side effect. Our tool needs to generate both variants.
Brand logo in mail client
Supporting mail clients can showing your company logo through BIMI. It's an emerging standard. It's a great way to build trust towards your clients. You need DKIM/DMARC and SPF set in your DNS entries and have them validated. Then set another TXT DNS entry that points to your logo in SVG format. That's it.
Markdown to HTML transformation
The tool takes the newsletter written in Markdown and the HTML template and transforms it into HTML and CSS. As said, the template comes from the third-party API and CSS is a tricky topic in emails.
A whole HTML compiler was created because of the messiness that you need to go through when you want to design emails that look good on a wide variety of email clients. Can you imagine that Outlook uses Word as an HTML rendering engine?! Even Outlook 2019!
Markdown-to-HTML converters create very simple markup without any classes or even inline styles. # converts to <h1> tags, a text block to a <p> tag, and so on. Nothing fancy! That's going to be the tricky part which perhaps answers why it hasn't been done so far.
Josh Comeau wrote an extensive essay about the state of HTML and CSS in emails. Rémi is a dedicated email developer who has been writing about emails many years. He goes through many details in this topic.
GMail supports embedded styles so we can do this MVP for those modern clients that support them. Problem solved! There's still the plain text version as a fallback.
Summary
It sounds crazy from a technical view point but not that unrealistic as I thought at the beginning. I'd love to hear your thoughts. Send me a DM on Twitter.