Markdown — Glossary

Markdown is a lightweight plain-text writing format that turns readable punctuation into headings, lists, links and emphasis, usually by converting it to HTML. John Gruber created it in 2004, with help from Aaron Swartz. The current precise definition is the CommonMark spec, version 0.31.2 from January 2024, and GitHub Flavored Markdown extends CommonMark.

How it works

A Markdown processor reads the text in two passes. It first finds blocks such as paragraphs, headings, lists, quotes and fenced code, then finds inline elements inside them such as emphasis, code spans and links. The output is usually HTML, though other targets exist.

Headings: one to six # characters followed by a space, so ## Title becomes an h2.
Emphasis: italic and bold, with underscores also accepted.
Lists: lines starting with -, * or +, or with a number of up to nine digits followed by . or ).
Code: backticks for inline code and fences of three backticks for blocks. Four spaces of indentation also makes a code block.
Links: [text](url).

Gruber's original 2004 description left many edge cases open, so implementations disagreed. CommonMark was written to remove those ambiguities and ships with a test suite. The input and output below were produced with the commonmark npm package, version 0.31.2.

# Release notes

Use **bold**, *italic* and `code`.

- first
- second

See [the spec](https://spec.commonmark.org/).

<h1>Release notes</h1>
<p>Use <strong>bold</strong>, <em>italic</em> and <code>code</code>.</p>
<ul>
<li>first</li>
<li>second</li>
</ul>
<p>See <a href="https://spec.commonmark.org/">the spec</a>.</p>

What is the difference between Markdown, CommonMark and GFM?

Markdown is the family of formats, CommonMark is the strict specification of its core, and GitHub Flavored Markdown (GFM) is a superset of CommonMark. The GFM spec, version 0.29-gfm from April 2019, adds five extensions: tables, task list items, strikethrough, extended autolinks and a filter for disallowed raw HTML. Other tools add footnotes, math or front matter in their own ways, so the same file can render differently between sites.

What file extension and media type does Markdown use?

Markdown files use the extension .md or .markdown, and the media type is text/markdown. RFC 7763, from March 2016, registers both. The media type requires a charset parameter, since no default exists, and has an optional variant parameter to name a dialect such as GFM.

Common pitfalls

No space after the hash: #NoSpace is a plain paragraph, not a heading. CommonMark requires a space or tab after the opening hashes. Run on commonmark and marked, both gave <p>#NoSpace</p>.
Single newline is not a line break: two lines in one paragraph stay in one paragraph. A hard break needs two trailing spaces or a backslash at the line end. Editors that strip trailing whitespace silently remove the break, so prefer the backslash.
Tables in plain CommonMark: a pipe table stays literal text under a strict CommonMark parser. The same table rendered as an HTML table in marked with GFM on. Check which flavor the target supports.
Raw HTML passes through: <script>alert(1)</script> came out unchanged from both parsers. Rendering untrusted Markdown without sanitizing the HTML is an XSS hole. The commonmark.js safe option replaces raw HTML with a comment, and a dedicated sanitizer after rendering is the stronger fix.
Long list numbers: 1234567890. is not a list item, because CommonMark caps list numbers at nine digits because 10 digits caused integer overflows in some browsers.

Related terms

XML — a tag-based markup language, the kind of syntax Markdown is meant to avoid writing by hand
YAML — another human-readable plain-text format written by hand
UTF-8 — the usual encoding for Markdown text files
CRLF — one of the three line endings CommonMark accepts, with LF and CR