• markdown
  • md
Image of Author
September 4, 2023 (last updated September 4, 2023)

The introduction to the CommonMark spec is a great introduction to markdown as a syntax.

Markdown is a plain text format for writing structured documents... It was developed by John Gruber (with help from Aaron Swartz) and released in 2004 in the form of a syntax description and a Perl script ( for converting Markdown to HTML.

Gruber writes,

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.


In the CommonMark spec section why is a spec needed?, it explains,

John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously.... In the absence of a spec, early implementers consulted to resolve these ambiguities. But was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec... Because there is no unambiguous spec, implementations have diverged considerably... To make matters worse, because nothing in Markdown counts as a “syntax error,” the divergence often isn’t discovered right away.

CommonMark is an attempt to "specify Markdown syntax unambiguously".

Github flavored markdown (GFM)

The GFM spec is essentially a copy of the CommonMark spec with a few additions. According to the GFM spec section what is github flavored markdown,

GFM is a strict superset of CommonMark.