Links and Footnotes in Markdown
Updated  by  nm  2022-February-13

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

## About Markdown

One reason 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][mdextra], 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 the Markdown source code of *this* article to test tools.


[mdextra]: 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://wikipedia.org/wiki/Lightweight_markup_language


 

## 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"`    | `a`
image          | `![alt text][id]`     | `[id]: URL "title"`     |  `img`
footnote     | `footnoted text[^id]`    | `[^id]: the footnote`   | `sup a`



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

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

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



 

## Link Examples

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

 

### 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

```

 

### 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/

 

## Footnote Examples

***Important:*** 
Markdown footnote syntax is not standardized and the footnote syntax used in the source of this article does not work in some Markdown renderers.

<!--
TODO MAYBE:
For example [Goldmark](https://github.com/yuin/goldmark), which is Hugo's default Markdown renderer.
-->

 


### 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.
```

 

### Inline Footnote Example

Some Markdown parsers, for example Blackfriday, Mmark, 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 Blackfriday, Mmark, 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.

* automatic angle-bracketed link, e.g. <https://example.org> (used in footnote 5)
* 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...*



 

## View the Source

Here is the source code of the “main matter”^[A document often comprises front matter, main matter, and back matter.] of this article. This does not include the source code of the header, <abbr title="Table Of Contents">TOC</abbr>, News section, or anything below *this* sentence (other than the footnotes that are specified in the source code above this sentence).