Links, Footnotes, and Abbreviations in Markdown

One reason that Markdown1 is so popular is that it's much easier for a human to read and write than HTML. To make Markdown as readable as possible, I like to specify links by reference, rather than inline. Some flavors of Markdown, for example Markdown Extra, support footnotes and abbreviations, which are also specified by reference. I'm writing this article for two reasons:

  1. As a note to myself about the by-reference syntax of links, footnotes, abbreviations, and images.
  2. To create a Markdown file that I can use to test Markdown tools. All flavors of Markdown support by-reference links, but only some support footnotes2 and abbreviations. I'll use this markdown file to test tools.

Cheatsheet for By-Reference Markdown Syntax

Here's a table that summarizes what can be specified by reference in Markdown. For completeness, I include the Markdown markup for images, which can also specified by reference. To conserve space in the table, I use definitium to mean defined text.

WhatInline MarkdownReference MarkdownHTML Tags
link[linked text][id][id]: URL "title"a
link[linked text][][linked text]: URL "title"   a
image![alt text][id][id]: URL "title"img
footnote   footnoted text[^id]   [^id]: the footnotesup a
abbrdefinitium*[definitium]: definitionabbr
    

Tip 1: "title" is optional

Tip 2: id is not case sensitive

Tip 3: definitium is case sensitive

Examples

In the Markdown code examples below, the colon (:) represents a random number of lines of text that can separate the inline Markdown from the reference Markdown.

A Markdown tool that I'm testing, and actually using to write this article, is MdCharm and it does not (yet) support abbreviations.

Here is the Markdown code for the previous sentence:

A Markdown tool that I'm testing, and actually using to write this article, is [MdCharm][] and it does not (yet) support abbreviations.
:
[mdcharm]: https://github.com/zhangshine/MdCharm

An online tool for comparing flavors of Markdown is John MacFarlane's Babelmark 2.

Here is the Markdown code for the previous sentence:

An online tool for comparing flavors of Markdown is John MacFarlane's [Babelmark 2][b2].
:
[b2]: http://johnmacfarlane.net/babelmark2/

Footnote Example

Unfortunately, most Markdown tools do not support abbreviations.3

Here is the Markdown code for the previous sentence:

Unfortunately, most Markdown tools do not support abbreviations.[^ab]
:
[^ab]: On a web page, an abbreviation is usually rendered as a mouseover pop-up definition. In HTML4, abbreviations are specified using the `abbr` or `acronym` tag. In HTML5, only the `abbr` tag is used.

Abbreviation Example

IMHO, the word “abbreviation” is a bit of a misnomer in this context.

Here is the Markdown code for the previous sentence:

IMHO, the word *abbreviation* is a bit of a misnomer in this context.
:
*[IMHO]: In my humble opinion
*[misnomer]: inappropriate name

Markdown Used in This Article

Here is a list of the Markdown syntax that I used to create this article.

  • inline link
  • by-reference link
  • automatic not-bracketed link, e.g. https://example.org/ (used below in footnote 1)
  • footnote
  • abbreviation
  • header
  • ordered list
  • unordered list (this list is the example of that)
  • emphasized text (bold, italics, and bold italics)
  • code span
  • code block
  • table
  • and more...

Abbreviations used in this article (that don't work in Hugo's Markdown flavors)

*[IMHO]: In my humble opinion
*[misnomer]: inappropriate name
*[definitium]: text that is defined

View the Source

To view the Markdown behind this page, see:

  www.ii.com/included/links-footnotes-abbreviations-markdown.mmark

Endnotes


  1. Markdown is a lightweight markup language that I wrote about in http://nancym.tumblr.com/post/43431761935/maybe-if-i-learn-markdown-ill-blog-more.
  2. Footnotes are also known as endnotes.
  3. On a web page, an abbreviation is usually rendered as a mouseover pop-up definition. In HTML4, abbreviations are specified using the abbr or acronym tag. In HTML5, only the abbr tag is used.