Markdown Preview

Which Markdown are you writing?

There is no single Markdown. John Gruber's 1.0 specification from 2004 left many cases undefined, so implementations diverged. CommonMark exists to pin down the ambiguities precisely. GitHub Flavored Markdown extends CommonMark with tables, strikethrough, task lists, autolinking and fenced code blocks with language hints. This previewer targets GFM, because that is what most people are actually writing when they write Markdown.

The practical consequence is that a document that renders correctly in one tool may not in another. Nested lists, HTML mixed into Markdown, and line-break handling are the three areas that differ most between renderers.

The line-break trap

A single newline in Markdown does not produce a line break. Consecutive lines are joined into one paragraph, which surprises people writing addresses or poetry. To force a break you either end the line with two trailing spaces, which is invisible and easy to strip, or use a backslash at the end of the line in CommonMark, or insert an explicit <br>. A blank line between blocks starts a new paragraph, which is usually what you actually want.

Nested lists need consistent indentation

Sub-list indentation is measured from the start of the parent item's content, not from the line start. With a - marker that means two spaces; with 1. it means three. Mixing tabs and spaces here is the most common cause of a nested list rendering flat. When a list collapses unexpectedly, normalise the whitespace before anything else.

Tables are stricter than they look

A GFM table requires a header row and a delimiter row of hyphens. Colons in the delimiter row set alignment: leading for left, trailing for right, both for centre. Pipes at the start and end of each row are optional but make the source far easier to read. A table with a mismatched column count between header and body rows will render with empty or dropped cells rather than failing loudly.

Local rendering

Conversion happens in your browser. Draft documentation, release notes and internal READMEs stay on your machine, and there is no server round trip on every keystroke.