Andrew Pilsch Blog

Stylish Markdown Footnotes w/ jQuery

05 Dec 2014

This blog post introduces a new jQuery plugin I’ve written, called jquery-inline-footnotes. It converts footnotes generated by Markdown—an HTML pre-processor driving a lot of static-site generators such as Middleman, Hugo, and Jekyll that academics use for blogging—into a design pattern more familiar and comfortable for web use.

In print documents, footnotes are in the footer of a document, either at the bottom of the page (preferred) or at the end of a chapter or book as end notes (i hate end notes). Both of these design patterns are great, but how do you place something at the bottom of the page when, as on the web, you don’t have pages like a codex?

One solution to this is to emulate end notes, enhanced for web usage. In this model, footnote references are generated in the following manner:

<p>Some text.<sup id="fnref:foobar"><a href="#fn:foobar">1</a></sup></p>...<ol>	<li id="fn:foobar">Footnote content.<a href="#fnref:foobar">&#8617;</a>.</li></ol>

This pattern places the footnotes at the bottom of the document, in a numbered list. It converts each numbered footnote into an internal link that transports users to the footnote content and provides a link back to the reference to move them back to where they were in the content, when finished.

Importantly, this design pattern is also automatically generated by a number of Markdown pre-processors, in the following manner:

Some text. [^foobar]...[^foobar]: Footnote content.

This pattern is what I use on this blog, because I want my site to have a more classically scholarly feel. However, in conversations with Shawna Ross, it became clear that not everyone likes this pattern. As she pointed out, “I don’t read with my fingers,” which I think is an interesting point about how disruptive this pattern can be.

Reading with your eyes instead of your fingers is also a problem with Bigfoot, one of the most interest and oft-emulated attempts to rethink the footnote for the screen. In that solution, HTML footnote content is removed from the bottom of the document and footnote references are replaced with a clickable lozenge (see the screenshot below) that, when clicked, pops up a box containing footnote content, as you can see below:

Bigfoot's Footnote Solution
Bigfoot’s elegant-looking, though not eye-reading friendly solution

What Bigfoot offers in terms of elegance doesn’t compensate for the fact that you still have to read with your fingers.1 However, a lot of big sites, notably Grantland, are using a similar solution for footnotes.

The other major idea, which Grantland actually used to use (as documented by this Codepen), is to place footnotes in the sidebar of the article, positioned using CSS. This way, the footnote content is visibly present but not obstructive. Moreover, the user doesn’t have to click anything to see the footnote. For an example of these in the wild, check out my colleague Chris Forster’s blog, which prompted this discussion in the first place.

However, there are problems with this approach. These footnotes can take up room in the design, which is why I suspect Grantland dropped them (the space that used to hold their elegant, easily accessible footnotes is now full of ads). More importantly, the don’t work on mobile browsers, where, following good responsive design principles, the content really should fill most of the screen in a single column, without a sidebar for footnotes.

So, how to solve this? I’ve written a plugin, called jquery-inline-footnotes, that uses screen size detection to switch between positioning the footnotes in the sidebar if the screen is wide enough and positioning them as inline notes that accordion (see below) if there is not enough screen real estate to display footnotes in the sidebar.

Accordion footnote behavior on mobile
Accordion footnote behavior in mobile browsers

I’ve put together a demo of this footnote functionality, if you’re interested in seeing how jquery-inline-footnotes works live.

The final major issue with this approach is making sure that footnotes aren’t positioned on top of one another. If two footnote references are on the same line or if the content of one footnote overlaps the line of main content containing a second reference, the two footnotes will overlap in the sidebar (which you can see below).

Overlapping footnotes in a sidebar
Overlapping footnotes in a document’s sidebar

To fix this, I wrote a collision detection algorithm that parses the footnotes using another plugin, jquery-overlaps to determine overlap and move footnotes down the sidebar to prevent this behavior. The detector moves footnotes down the page until none overlap.

So, all in all, jquery-inline-footnotes is a plugin that converts footnotes generated by Markdown into responsive, elegant, eye-reading friendly footnotes that sit in the sidebar on large-enough screens and convert into simple, inline accordions when there isn’t enough screen real estate to place footnotes in the sidebar.

The solution is basically drop-in and works out of the box with only a little CSS tweaking.

Please let me know if you have any questions or find this plugin useful!

  1. It also doesn’t help that Bigfoot is surprisingly difficult to install out of the box. I had to do a lot of tinkering to get it to work the few times I’ve used it for projects. 


Andrew Pilsch

Comments

comments powered by Disqus