Markdown HTML Converter

Markdown was written to look good before it's ever rendered — that was the whole point

John Gruber published Markdown in December 2004 with one explicit design goal: a plain-text file should be readable as plain text, not as a soup of HTML tags. A # Heading looks like a heading. A line with --- under it looks like it's underlined. The Perl script he shipped to convert it to HTML was almost secondary to that goal. Four years later, Stack Overflow (2008) and GitHub (2008) had both adopted it. GitHub Flavored Markdown then added tables, task lists, and fenced code blocks — none of which were in Gruber's original spec — and those extensions became what most developers actually think of as "Markdown" today.

CommonMark happened because the original spec had around 600 ambiguous edge cases

Gruber's spec left a lot underspecified on purpose, or just by accident. Two different Markdown parsers would take the same input and produce different HTML. That's a real problem when you're building documentation toolchains or multi-platform publishing workflows. John MacFarlane — the author of Pandoc — led the CommonMark effort starting in 2014: a fully specified, unambiguous Markdown standard with a test suite of 650+ examples. GitHub's Markdown renderer now uses CommonMark as its base layer. If your content has to render consistently across multiple tools, write to CommonMark syntax. Avoid extensions that only one parser supports.

Five constructs and exactly what HTML they produce

1. ATX headings — One to six # characters produce <h1> through <h6>. Setext headings — the kind with = or - underlines — produce identical output but cap at h2 and require more typing. ATX is almost always the right choice.
2. Emphasis — Single * or _ around text produces <em>. Double produces <strong>. Inside a word, use asterisks. Underscore behavior inside words differs between CommonMark and Gruber's original Markdown in ways that are annoying to debug. Asterisks are safe everywhere.
3. Fenced code blocks — Three backticks followed by a language hint like js or python produces <pre><code class="language-js">. The language class is what syntax highlighters in GitHub, VS Code, and static site generators use to color the output. Without it, you get a code block with no highlighting.
4. Tables (GFM) — Pipe-separated columns with a row of hyphens for the header separator produce a full <table> with <thead> and <tbody>. Not in CommonMark core, but supported as an extension in every major processor people actually use.
5. Task lists (GFM) — - [ ] and - [x] render as <input type="checkbox"> elements inside list items. GitHub makes them interactive in issue descriptions. Other renderers produce the HTML and leave the interaction to you.

Sending Markdown in email doesn't work the way most people expect

Email clients don't render Markdown. They render HTML, or they show plain text. The workflow is: convert your Markdown to HTML first, then send a multipart/alternative MIME message with both the HTML version and a plain-text fallback. Most email libraries — Nodemailer, PHPMailer, SendGrid's API — have separate html and text parameters for exactly this split. The Markdown source often works fine as the plain-text version as-is, which is convenient since that readability was the whole original design goal.