Links, Footnotes, and Abbreviations in Markdown
One reason that Markdown[^markdown] is so popular is that it's much easier for a human to read 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][mdx], 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, and abbreviations (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 and abbreviations. I'll use *this* markdown file to test tools. [mdx]: http://michelf.ca/projects/php-markdown/extra/ [^markdown]: Markdown is a [lightweight markup language][lml] that I wrote about in http://nancym.tumblr.com/post/43431761935/maybe-if-i-learn-markdown-ill-blog-more. [lml]: http://en.wikipedia.org/wiki/Lightweight_markup_language ## 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 are also specified by reference. To conserve space in the table, I use *definitium* to mean *defined text*. What | Inline Markdown | Reference Markdown | 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` abbr | `definitium` | `*[definitium]: definition` | `abbr`  |  |  |  ***Tip 1:*** `"title"` is optional ***Tip 2:*** `id` is not case sensitive; `definitium` *is* case sensitive ***Tip 3:*** To see this table, you might need to go to [the permalink page of this article](http://nancym.tumblr.com/post/59594358553/links-footnotes-and-abbreviations-in-markdown) ## 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. ### Link Examples A Markdown tool that I'm testing, and actually using to write this article, is [MdCharm][] and it does not (yet) support abbreviations. [mdcharm]: http://www.mdcharm.com/ 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]: http://www.mdcharm.com/ An online tool for comparing flavors of Markdown is John MacFarlane's [Babelmark 2][b2]. [b2]: http://johnmacfarlane.net/babelmark2/ 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[^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. 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. *[IMHO]: In my humble opinion *[misnomer]: inappropriate name 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 *[definitium]: text that is defined ## Where To Find More Examples This Markdown file tests a lot of Markdown syntax and soon I'll publish it on [GitHub](https://github.com/) so anyone can use it to test a Markdown tool or learn Markdown. Here is a list of the Markdown syntax I used to create this article: * inline link * by-reference link * automatic angle-bracketed link, e.g. `` * automatic not-bracketed link, e.g. `http://example.org/` * 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...* I hope this article is helpful to you. Do you have any feedback or suggestions?
