Links and Footnotes in Markdown

On This Page

News

2021-February-5  In this article, removed most of the information about the Markdown syntax for abbreviations and changed the title to Links and Footnotes in Markdown. To learn about abbreviations in Markdown, which AFAIK are only available in PHP Markdown Extra,1 see the 2014 version of this article at nancym.tumblr.com/post/59594358553/links-footnotes-and-abbreviations-in-markdown.

2021-February-5  As of today, this article is rendered with the Pandoc universal document converter rather than Hugo’s default Markdown renderer, Goldmark. I switched from Goldmark to Pandoc because I was in search of a Markdown flavor that I could plug in to Hugo that supports abbreviations. I did not find that, but I did discover that Pandoc supports inline footnotes and some other Markdown syntax that Goldmark does not support.2

2021-January-29  As of today, this article has been on the web for 7 years.🎂


About Markdown

One reason that Markdown3 is so popular is that it is 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 PHP Markdown Extra, support footnotes, which also can be 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, 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 footnotes. I’ll use this Markdown file to test tools.

 

Cheatsheet for By-Reference Markdown Syntax

Here is a table that summarizes what can be specified by reference in Markdown. For completeness, I include the Markdown markup for images, which can also be specified by reference.

WhatInline MarkdownReference MarkdownRendered
HTML 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

Tip 1: "title" is optional.

Tip 2: id is case insensitive.

Tip 3: id cannot contain whitespace.

 

In the Markdown source code examples below, a vertical ellipsis () represents a random number of lines of text and blank lines 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.

Here is the Markdown source code for the previous sentence:

A Markdown tool that I'm testing, and actually using to write this article, is [MdCharm][].
⋮

[mdcharm]: https://github.com/zhangshine/MdCharm

 

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

Here is the Markdown source code for the previous sentence:

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

[b2]: https://johnmacfarlane.net/babelmark2/

 

Footnote Examples

By-Reference Footnote Example

Most Markdown tools do not support abbreviations. Instead, you need to use raw HTML to specify abbreviations.4

Here is the Markdown source code for the previous sentence:

Most Markdown tools do not support abbreviations. Instead, you need to use raw HTML to specify abbreviations.[^abbr]
⋮

[^abbr]: In a desktop web browser, an abbreviation is usually rendered as a mouseover pop-up definition. In <abbr title="Hypertext Markup Language">HTML</abbr>4, abbreviations are specified using the `abbr` or `acronym` tag. In HTML5, only the `abbr` tag is used.

 

Inline Footnote Example

Some Markdown parsers, for example Pandoc and PHP Markdown Extra, also support inline footnotes.5

Here is the Markdown source code for the previous sentence:

Some Markdown parsers, for example Pandoc and PHP Markdown Extra, also support inline footnotes.^[Footnotes are also known as endnotes.] 

 

Markdown Used in This Article

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

 

View the Source

Here is the source of the “main matter”6 of this article. This does not include the source of the header, TOC, News section, or anything that is below this sentence (other than the footnotes that are specified in the source above this sentence).

<!-- NOTE TO SELF: This entire file is *published* in links-footnotes-markdown. -->

## About Markdown

One reason that Markdown[^markdown] is so popular is that it is 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 [PHP Markdown Extra][mdx], support footnotes, which also can be 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, and images.
1. 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 footnotes. I'll use *this* Markdown file to test tools.


[mdx]: https://michelf.ca/projects/php-markdown/extra/

[^markdown]: Markdown is a [lightweight markup language][lml] that I wrote about in <https://nancym.tumblr.com/post/43431761935/maybe-if-i-learn-markdown-ill-blog-more>.

[lml]: https://en.wikipedia.org/wiki/Lightweight_markup_language


&nbsp;

## Cheatsheet for By-Reference Markdown Syntax

Here is a table that summarizes what can be specified by reference in Markdown. For completeness, I include the Markdown markup for images, which can also be specified by reference. 


What           | Inline Markdown       | Reference Markdown     | Rendered<br>HTML Tags
:------------- | :-------------------  | :--------------------- | :-------
link           | `[linked text][id]`   | `[id]: URL "title"`    | `a`
link           | `[linked text][]`     | `[linked text]: URL "title"` &nbsp;&nbsp; | `a`
image          | `![alt text][id]`     | `[id]: URL "title"`     |  `img`
footnote &nbsp;&nbsp;  | `footnoted text[^id]` &nbsp;&nbsp; | `[^id]: the footnote`   | `sup a`



***Tip 1:*** `"title"` is optional.

***Tip 2:*** `id` is case insensitive.

***Tip 3:*** `id` cannot contain whitespace.



&nbsp;

## Link Examples

In the Markdown source code examples below, a vertical ellipsis (<code>&vellip;</code>) represents a random number of lines of text and blank lines that can separate the inline Markdown from the reference Markdown.

&nbsp;

### By-Reference Link Example 1

A Markdown tool that I'm testing, and actually using to write this article, is [MdCharm][].


[mdcharm]: https://github.com/zhangshine/MdCharm

Here is the Markdown source code for the previous sentence:


```
A Markdown tool that I'm testing, and actually using to write this article, is [MdCharm][].
⋮

[mdcharm]: https://github.com/zhangshine/MdCharm

```

&nbsp;

### By-Reference Link Example 2

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

[b2]: https://johnmacfarlane.net/babelmark2/

Here is the Markdown source code for the previous sentence:

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

&nbsp;

## Footnote Examples


### By-Reference Footnote Example

Most Markdown tools do not support abbreviations. Instead, you need to use raw HTML to specify abbreviations.[^abbr]

[^abbr]: In a desktop web browser, an abbreviation is usually rendered as a mouseover pop-up definition. In <abbr title="Hypertext Markup Language">HTML</abbr>4, abbreviations are specified using the `abbr` or `acronym` tag. In HTML5, only the `abbr` tag is used.


Here is the Markdown source code for the previous sentence:

```
Most Markdown tools do not support abbreviations. Instead, you need to use raw HTML to specify abbreviations.[^abbr]
⋮

[^abbr]: In a desktop web browser, an abbreviation is usually rendered as a mouseover pop-up definition. In <abbr title="Hypertext Markup Language">HTML</abbr>4, abbreviations are specified using the `abbr` or `acronym` tag. In HTML5, only the `abbr` tag is used.
```

&nbsp;

### Inline Footnote Example

Some Markdown parsers, for example Pandoc and PHP Markdown Extra, also support inline footnotes.^[Footnotes are also known as endnotes.] 

Here is the Markdown source code for the previous sentence:

```
Some Markdown parsers, for example Pandoc and PHP Markdown Extra, also support inline footnotes.^[Footnotes are also known as endnotes.] 
```



&nbsp;

## Markdown Used in This Article

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

* automatic angle-bracketed link, e.g. &lt;https://example.org&gt; (used below in footnote&nbsp;4)
* by-reference link
* inline link
* by-reference footnote
* inline footnote
* 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...*



&nbsp;

## View the Source

Here is the source of the &ldquo;main matter&rdquo;^[A document comprises front&nbsp;matter, main&nbsp;matter, and back&nbsp;matter.] of this article. This does not include the source of the header, TOC, News section, or anything that is below *this* sentence (other than the footnotes that are specified in the source above this sentence).

 

If you are wondering how I get Hugo to display the source of part of this article inside this article (just above here), here is the story: I put the source fragments of this article into a Hugo leaf bundle and then use my custom get-leaf-text shortcode and Hugo’s built-in highlight shortcode to get and highlight the “main matter” fragment. 

 

Endnotes


  1. PHP Markdown Extra (which is also known as PHPME or Markdown Extra or MDExtra) is available on Tumblr and is the flavor of Markdown that I originally wrote this article in. As far as I can tell, it is the only Markdown flavor that supports abbreviations (with a Markdown syntax that is not raw HTML).↩︎

  2. To learn about Goldmark, Pandoc, and other renderers that Hugo supports, see Infinite Ink’s Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText.↩︎

  3. Markdown is a lightweight markup language that I wrote about in https://nancym.tumblr.com/post/43431761935/maybe-if-i-learn-markdown-ill-blog-more.↩︎

  4. In a desktop web browser, 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.↩︎

  5. Footnotes are also known as endnotes.↩︎

  6. A document comprises front matter, main matter, and back matter.↩︎


Comments 👍 👎 📝

To comment, you must be signed in to GitHub.