Automatic footnotes

[John Gruber]

Aaron Swartz <aaronsw at gmail.com> wrote on 04/06/05 at 8:03pm:

> > off writing a new MT plugin to handle footnotes (which would include
> > both superscripting the footnote numbers, and also automatically
> > generating the id attributes to make them clickable links within the
> > article; that's not something that would belong in Markdown).
> 
> Why not?

Because I don't think it's possible to generate HTML output that
everyone would agree upon. But I could be wrong.

When we create emphasized spans, everyone knows it should be
`<em>...</em>`.

When we create a link, everyone knows it should be
`<a href="url">...</a>`.

But what's the markup for footnotes?

At the minimum, you need a few things.

One technical issue is that you need unique identifiers for the
anchor references, so that when you click footnote 1, it takes you
to where that footnote lives on page. At first thought, you might
think this is easy, just number them:

    http://example.com/article-with-footnotes#fn1
    http://example.com/article-with-footnotes#fn2
    ...

This works for an individual article, but it doesn't work for an
index page -- a page that might contain multiple footnoted articles.
Footnote id's need to be site-wide unique. In MT (or most other
weblog systems), one obvious solution would be to use the post ID
number. The first footnote for post 324 might have the id `p326-fn1`
or something like that.

Prescribing these id's doesn't strike me as something that belongs
in the syntax. It seems tool-specific to me. Perhaps the syntax
could just state that generating unique id's is left to the
implementor, however.

The larger question is, what does the markup look like?

Let's pretend this is my input:

    Wouldn't it be nice if Movable Type allowed for del.icio.us-like
    tags [^1] instead of its current rigid and restrictive category
    system?

    [^1]: Flickr has a nice tagging system, too, with a very nice      
          JavaScript-powered web-app UI.

Where the `[^1]` is the footnote reference, and the `[^1]:` is the
footnote definition.

How do you mark that up?

The footnote isn't too hard. Something like this shouldn't be
objectionable:

    ... tags <sup><a href='#fn1-227'>1</a><sup> instead of ....

But how do you markup the footnote itself?

    <p class='footnote'><sup>1.</sup> Flickr has a nice tagging
    system, too, with a very nice JavaScript-powered web-app UI.</p>

Would be one way.

    <div class='footnote'>
    <p><sup>1</sup> Flickr has a nice tagging system, too, with a
    very nice JavaScript-powered web-app UI.</p>
    </div>

Would be another (and if you had more than one footnote, they could
all go in that one div).

But either way, I don't see any way around presupposing that the
user has a CSS class defined for footnotes. Nothing else in Markdown
requires this.

Another Q: Who's to say where footnote definitions should go? The
obvious and traditional answer is together at the bottom of the
page. That makes complete sense for print, but on a web page, maybe
you'd want to put them right under the paragraphs where you're
defining them. It's easy to move your eyes down to the bottom of a
page in a book to read a footnote, but it's harder to scroll/jump
around a web page.

I've seen some very interesting footnote and footnote-ish designs
for the web where the notes appear and disappear either on top of,
or in the margins next to, the main text. Using JavaScript and CSS
DOM stuff.

I think something like that might be using the nature of the web to
its full advantage, and could make the concept of footnoting more
readable/usable than in the print world.

The other feature I've been thinking about (I started using
footnotes on Daring Fireball a few weeks ago) is a back-link from
the footnote definition back to the place in the text where it was
noted. E.g., in the rendered output, you'd see:

    1. Flickr has a nice tagging system, too, with a very nice
       JavaScript-powered web-app UI.  ->

Where the "->" would be an arrow-ish character that you could click
to return to the place in the text where footnote 1 was references.

Again, what's the markup for that? I'd probably want to use some
sort of Unicode arrow character. RIGHTWARDS ARROW WITH HOOK, perhaps
(&#8618; as an HTML entity).

But I'll bet $5 that doesn't work in Win/IE5, and maybe not in
Win/IE6 if you don't have the right Unicode enabled fonts installed.
It works in Firefox (although on Windows you might still need
certain fonts) and it works on Mac OS X.

So people might want the backlink to say "Back", or to use some
other entity.

To me these seem like reasons not to build footnoting into Markdown
itself. On the other hand, I'm going to do something about
footnoting, because I want to use them liberally at Daring Fireball
and marking them up by hand just stinks.

One counter-argument for including them in Markdown would be that if
you don't like the way I've decided to mark them up, don't use
Markdown's footnoting feature.

-J.G.