data · 6 min read

Markdown to HTML — what converts, and what does not

Your table works on GitHub and disappears in the converter. Neither is broken; they implement different Markdowns.

Markdown was described in 2004 as a way of writing that reads well as plain text and converts to HTML. The description was informal and left a great many cases undefined, so every implementation resolved them differently and all of them called the result Markdown.

Two decades later there are two things worth knowing about, and the difference between them explains almost every surprise.

CommonMark and GitHub Flavored Markdown

CommonMark is a precise specification with a test suite, written to settle the ambiguities. It defines exactly what happens with nested lists, with emphasis inside words, with a list interrupted by a paragraph — the cases that used to differ between tools.

GitHub Flavored Markdown is CommonMark plus four additions people now assume are core: tables, strikethrough, task lists and automatic linking of bare URLs.

That last point is the practical one. Tables are an extension. A converter implementing CommonMark faithfully will render your table as a paragraph full of pipe characters, and it is not wrong.

What every converter agrees on

Headings with hashes, paragraphs separated by blank lines, emphasis with asterisks or underscores, ordered and unordered lists, links and images in bracket-parenthesis form, blockquotes, inline code with backticks, fenced code blocks, and horizontal rules.

That is the portable subset. Anything written with only those converts identically everywhere, and it covers most documents.

What varies

Tables, strikethrough, task lists, autolinks — GFM extensions. Widely supported and not universal.

Footnotes, definition lists, abbreviations — extensions from other dialects, supported by fewer tools.

Front matter — the YAML block at the top of a file. Not Markdown at all; a convention that static site generators strip before parsing. A general converter renders it as a paragraph with a horizontal rule above it.

Raw HTML — passed through by most, stripped by anything sanitising, and the right behaviour depends entirely on where the Markdown came from.

Line breaks, the recurring confusion

A single newline is a space. Markdown reflows paragraphs, so a sentence split across three lines in your editor becomes one line of prose.

A blank line starts a new paragraph. To break a line within a paragraph, end it with two spaces or a backslash.

The two-space rule is invisible in every editor, which is why it causes so much trouble — trailing whitespace trimmers remove it silently, and the document changes shape with no visible edit. The backslash is uglier and survives.

Converting the other way

HTML to Markdown works and is lossy in a specific way: anything Markdown has no syntax for is dropped. Classes, inline styles, most attributes, and deeply nested structure all flatten.

So a round trip does not return the original. That is fine when the point is to extract readable text from a page — which is the usual reason — and it is worth knowing before using it as a storage format.

Where the output goes

A converter gives you a fragment, not a document — headings and paragraphs, no <html>, no head, no styling. That is usually what you want, since it is going into a template.

If it is being published, two things follow. Anything containing user-written Markdown needs sanitising, because raw HTML passes through by default and a script tag is raw HTML. And the fragment needs a stylesheet — unstyled headings and lists look like a document from 1995, which is why converted output so often looks unfinished.

The short version

Stick to the portable subset and it converts identically everywhere. Tables and task lists are GFM extensions, so check what your converter implements before assuming something is broken. And remember that a single newline is a space — most surprises are that.

Questions

Why did my Markdown table not convert?

Tables are not part of original Markdown. They come from GitHub Flavored Markdown, which most converters support and some do not. The same applies to strikethrough, task lists, automatic links and footnotes — all extensions rather than core syntax.

Is there a Markdown standard?

Not one. The original 2004 description left many cases undefined, so implementations diverged. CommonMark is a careful specification that settles the ambiguities, and GitHub Flavored Markdown is CommonMark plus tables, strikethrough, task lists and autolinks. Most tools follow one of those two.

Can I put HTML inside Markdown?

Usually yes — most converters pass raw HTML through untouched, which is how people embed video or add attributes. Converters that sanitise their output will strip it instead, and they are right to when the Markdown came from a user.

Why is my line break being ignored?

A single newline is treated as a space, because Markdown reflows paragraphs. A blank line starts a new paragraph, and two trailing spaces or a backslash at the end of a line force a break within one. The two-space rule is invisible in an editor, which is why it is the more confusing of the two.

How do I convert HTML back to Markdown?

It works, and it is lossy in one direction: anything Markdown cannot express — classes, inline styles, attributes, most nested structure — is dropped or flattened. Round-tripping a document through both conversions does not return what you started with.

Tools from this guide