Reference

Markdown, explained

Markdown is plain text with a small set of punctuation rules. The rules are simple; the ambiguities are not. These entries state the syntax, the CommonMark behaviour and where GitHub Flavored Markdown adds to it.

CommonMark is the baseline

Markdown started as a Perl script with a loose description. CommonMark turned that description into a precise specification with a reference implementation, and most modern parsers follow it. When a document renders differently on two sites, the difference is usually an extension or a legacy parser, not the core syntax.

GitHub Flavored Markdown (GFM) is a superset: it adds tables, task lists, strikethrough and autolinks while staying compatible with CommonMark. Entries below mark which behaviour is core and which is an extension.

Whitespace carries meaning

Markdown uses blank lines, indentation and line endings as syntax. A blank line separates blocks; two trailing spaces or a backslash create a hard line break; four spaces of indentation can turn a line into a code block. An editor that strips trailing whitespace can silently change the rendered output.

Raw HTML is allowed in most implementations, which is convenient and also a security concern. A renderer that accepts untrusted input must sanitize the output rather than trusting the source text.

All entries

New tools, straight to your inbox

One short email when we add tools worth using. No spam, unsubscribe anytime.