Footnotes extension to Markdown 1.0.1

Downloads

• MarkdownFN - a modified Markdown processor that adds the ability to create footnotes
• Patch - These are the changes made to John Gruber's Markdown script

Introduction

When I write, I often like to use footnotes (and parentheticals ¹) to add asides or extra information that is related, but a digression. I also like to use Markdown formatting for writing documents and, unfortunately, Markdown does not have any special support for making footnotes ².

Rationale

One of the primary advantages of any footnoting system is that it should free the writer from needing to constantly renumber and re-order the footnotes as they write, re-write, and edit. The system will take care of that when converting to HTML. Even if the document won't be converted to HTML, the references are strings and have no inherent order. Once finished writing, there's no re-numbering (though re-ordering will need to be done manually).

Syntax

I've added footnote support with the following syntax, which is similar to reference syntax for images and links.

This is a line with a footnote reference {F}.

{F}: This is the footnote

Which generates the following HTML

<p>This is a line with a footnote reference <sup id="fnref:1" name="fnref:1"><a href="#fn:F"  class="fn-button" rel="footnote">1</a></sup>.</p>

<div class="footnotes"><hr class="footnote-separator" />

<ol><p><li class="footnote" name="fn:F" id="fn:F">This is the footnote<a href="#fnref:1" title="Return to article">⏎</a></li></p>

</ol></div>

If the footnote needs to be longer than a line

This is a line with a footnote reference {F}.

{F}: {You can wrap the whole footnote in brackets.

This isn't particularly elegant, but it works.}

Each block will get it's own <p> tag like this

<p>This is a line with a footnote reference <sup id="fnref:1" name="fnref:1"><a href="#fn:F"  class="fn-button" rel="footnote">1</a></sup>.</p>

<div class="footnotes"><hr class="footnote-separator" />

<ol><p><li class="footnote" name="fn:F" id="fn:F">You can wrap the whole footnote in brackets.</p>

<p>This isn't particularly elegant, but it works.<a href="#fnref:1" title="Return to article">⏎</a></li></p>

The conversion creates a numbered link (1, 2, 3, 4, etc.) at the footnote reference and a return link at the end of the footnote. Regardless of where the footnotes are in the text, they will be at the bottom of the generated output in the order they referenced.

Additionally, the generated links are compatible with the bigfoot.js jQuery plugin for further footnote fancying.

Differences from other Syntax

According to the MultiMarkdown footnote page Gruber prefers a different syntax that's closer to the link and image syntax. I didn't know this when I decided on my syntax, but I think I prefer mine ³. My admittedly post-hoc reasoning is that footnotes are fundamentally different, semantically, from links and images and should have reasonably different syntax to communicate that.

If Markdown's syntax should be "as readable as possible" and the document should be "publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions" ⁴ then Markdown footnotes should not be inline and should look as much like printed footnotes as possible. The Gruber-proposed [^ref] syntax looks reasonably like a footnote would (with ^ alluding to the exponentiation operator -- and exponents are superscripts in print, just like footnote references) but it looks too much like a link. It also allows for in-line footnotes, which I don't think is "publishable as-is". In-line footnotes are parentheticals with weird brackets.