A Markdown file does not say which dialect it is written in. This page covers the versions there are, the five extensions GitHub Flavored Markdown adds to CommonMark (sections 4.10, 5.3, 6.5, 6.9 and 6.11 of that specification), and two common additions that no specification defines.
Versions
| Version | Date | What it is |
|---|---|---|
| Markdown | 2004 | John Gruber’s syntax description and Perl script, with Aaron Swartz. It left many cases undefined, and implementations disagreed. |
| CommonMark 0.31.2 | January 2024 | A complete, unambiguous specification of the core syntax, with a test suite of examples. The basis of the pages on this site. |
| GitHub Flavored Markdown 0.29-gfm | April 2019 | CommonMark (at version 0.29) with five extensions, which GitHub uses for its comments and files. |
The two specifications differ in small ways because GFM is based on an earlier version
of CommonMark. For example, its list of type 6 HTML block names has source
and lacks search. Most other Markdown dialects are CommonMark or the
original syntax with extensions of their own.
The media type is text/markdown, registered by
RFC 7763. Its charset
parameter is required, and an optional variant parameter names the
dialect, using values listed in RFC 7764.
4.10 Tables (GFM)
A table is a leaf block: a header row, a delimiter row and zero or more data rows. Each row is split into cells by unescaped pipes. Leading and trailing pipes are optional, and spaces around a cell’s content are removed. Block-level elements cannot go in a table; its cells hold inlines only.
The delimiter row holds only hyphens, with optional colons at either end of a cell,
and sets each column’s alignment: :-- left, :-: centre,
--: right. Its number of cells must match the header row’s, or the lines
are not a table at all.
| abc | defghi |
:-: | -----------:
bar | bazA data row with fewer cells than the header is filled out with empty cells, and one
with more cells has the excess ignored. A pipe inside a cell, even in a code span, must
be escaped as \|. The table ends at the first blank line or the start of
another block-level structure, which means an unindented line of text that begins
no other block is taken as another row.
5.3 Task list items (GFM)
A list item whose first block is a paragraph beginning with a task list item
marker: optional spaces, a left bracket, a space or an x in either
case, and a right bracket, then white space before the rest of the text. The item is
shown with a checkbox, ticked for x.
- [ ] to do
- [x] done
- [ ] nested6.5 Strikethrough (GFM)
Text wrapped in a matching pair of one or two tildes, using the same flanking rules as
* in emphasis. A run of three or
more tildes does not make a strikethrough. The spans must not contain a blank line, since
blocks are settled first.
6.9 Autolinks, extended (GFM)
Some links are recognised with no angle brackets. They can begin only at the start of a
line, after white space, or after *, _, ~ or
(.
| Kind | Recognised when | Link goes to |
|---|---|---|
| www | www. then a valid domain | http:// and the text |
| URL | http://, https:// or ftp://, then a valid domain | The text |
Letters, digits and . - _ +, then @, then letters, digits and . - _, with at least one period; the last character may not be - or _ | mailto: and the text | |
| Protocol | mailto: or xmpp: followed by an e-mail address; xmpp: may also have a / and a resource after it | The text |
A valid domain is segments of letters, digits, underscores and hyphens
separated by periods, with at least one period, and with no underscores in the last two
segments. After the domain, a link continues to the next white space or
<. Then:
- Trailing
?,!,.,,,:,*,_and~are not part of the link, though they may appear inside it. - If it ends in
), and has more closing than opening parentheses, the extra closing ones are left out. - If it ends in
;and looks like an entity reference, the reference is left out.
6.11 Disallowed raw HTML (GFM)
When HTML is written out, nine tags are made harmless by replacing the leading
< with <, because they are unusual and affect how the
page around them is shown: title, textarea, style,
xmp, iframe, noembed, noframes,
script and plaintext. Other HTML passes through unchanged.
Footnotes (not specified)
GitHub and other tools support footnotes, though neither CommonMark nor the GFM
specification defines them. A reference is [^label], and the definition is
[^label]: at the start of a line, followed by its text, which may continue
on following indented lines. Footnotes are numbered in the order they are first
referenced and shown at the end of the document. A reference with no definition is
plain text.
Front matter (not specified)
Many site generators and tools read metadata from a block at the top of the file,
between a line of --- and another of ---, usually written in
YAML. It is no part of any Markdown specification: to CommonMark, the same text is a
thematic break, then a heading or paragraph. A file with a real first thematic
break is therefore ambiguous, and tools disagree.
---
title: Packing list
draft: true
---In the viewer
The viewer reads a file as CommonMark with these extensions, since nothing in the file
can say otherwise. Each appears as a named node in the structure tree, the HTML tab shows
what it means in HTML, and the Overview counts them. Front matter is recognised only
when the lines between the two --- markers look like YAML, so a document
that merely starts with a thematic break keeps its first lines.