markdown

Aliases
  • markdown
  • md
  • markdown tips and tricks
  • md tips and tricks
Image of Author
September 12, 2022 (last updated March 14, 2025)

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 (Markdown.pl) 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.

CommonMark

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 Markdown.pl to resolve these ambiguities. But Markdown.pl 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.

Syntax

This is [a link to my website](https://gatlin.io)
This is [a reference-style link to my website][1]

[1]: https://gatlin.io
This is [a titled link](https://gatlin.io "gatlin.io"). 

A "titled" link is useful when converting markdown to html, as it translates to hover text. E.g., hovering over the titled link above would show the popup text "gatlin.io".

Footnotes

A footnoted[^1] sentence.[^2]

[^1]: Footnote one, inline
[^2]:
    Footnote two,
    which is
    multi-line

How footnotes get converted to html is dependent on your conversion tool of choice. (As best I can tell, footnotes are not covered in CommonMark or GFM specs, see markdown for more.) Processing tools will usually append a new section at the end of your content and hyperlink to it via linked superscripts.

Resources