jQuery plugin to create inline plugins from Markdown-created HTML footnotes.
JavaScript CSS HTML Ruby
Clone or download

README.md

jquery-inline-footnotes

This plugin is designed to convert footnotes generated by Markdown. It converts the automatically generated HTML (typically an ordered list with internal links) into a sidebar (as on sites like Grantland or Medium) for browsers big enough to show them and into inline footnotes that snap down, accordion-style, on mobile browsers and small screens.

With the sidebar footnotes, this plugin also handles collision detection. With this feature, two footnotes will not display overlapping one another.

See an example at http://oncomouse.github.io/inline-footnotes.html.

Also, this blog post discusses some of the reasoning behind this plugin.

Syntax Example

Assuming you have some markdown that looks like this:

Sometext.[^foobar]

[^foobar]: Footnote text!

I am assuming that the footnotes generated when Markdown converts to HTML look something like this:

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

From this style of footnote (which a number of Markdown engines generate), this plugin converts them into asides on large screens and accordion-style inline footnotes on smaller devices and screens.

Usage

In addition to jQuery, jquery-inline-footnotes depends on jquery-overlaps, however the minified version in dist/ already includes the plugin, so you don't have to include it separately. These can be installed using bower or downloaded separately. However you do it, you need to include some variation on the following code at the bottom of your document:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js" type="text/javascript"></script>
<script src="/dist/jquery.inline-footnotes.min.js" type="text/javascript"></script>
<script>
  $(document).ready(function() {
  	$.inlineFootnotes();
  });
</script>

You also need to include the contents of jquery.inline-footnotes.css) somewhere in your site's CSS.

As the width of your content column may allow smaller screens to display sidebar footnotes, check the "Configuration" section below.

Configuration

Much of the position and appearance of the footnotes is controlled through CSS. There are both CSS and SASS versions of the default CSS code in stylesheets/. There are a lot of options to customize and you will probably need to change things in your site.

One very important note about configuration: the default minimum window width of 1155 is the assumed minimum size of the window needed to display footnotes in the sidebar. This value is probably different for your application. You have to change this value in two places: in the CSS file, there is a media query (@media screen and (min-width: 1155px)) that controls the styles for accordion and sidebar footnotes. Additionally, the column width must be passed to the $.inlineFootnotes() function call as an option (see below). Also, see the examples for how to do this (below).

The following options (with their meaning in comments) may be passed in an options object to the $.inlineFootnotes() function at initialization:

$.inlineFootnotes({
	columnWidth: 1155, // minimum width of the screen necessary to display footnotes
	mediaQuery: null, // copy & paste the media query from your CSS file, if you prefer (and have polyfilled window.matchMedia)
	overlapOffset: 5, // padding (in pixels) between overlapping footnotes
	footNoteID: 'fn:', // base string of ID for footnotes
	footNoteRefID: 'fnref:', // base string of ID for footnote reference links
	inlineFootNoteID: 'fnote_', // base string of the IDs of elements we are attaching
	maxCollisionCycles: 8, // Number of iterations of collision detection to run, may need to increase.
	DEBUG: false // Display debugging information?
});

Usage Examples

As mentioned above, you will most likely need to change the minimum window size at which footnotes display in the sidebar. Below is an example for doing so, in which the minimum size is changed from the default (1155px) to a smaller size (960px).

In stylesheets/jquery-inline-footnotes.css, the media query (@media screen and (min-width: 1155px) {) is changed to

@media screen and (min-width: 960px) {

...

}

Additionally, the plugin must be initialized using one of the following two options:

In the first (easiest), the edited media query is simply passed to the function:

<script>
	$(document).ready(function(){
		$.inlineFootnotes({
			mediaQuery: '@media screen and (min-width: 960px)'
		})
	});
</script>

This solution is simple (copy & paste), but does make use of the window.matchMedia, which is not supported in older browsers. You can, however, polyfill matchMedia by including Modernizr in your application (include <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.8.3/modernizr.min.js"></script> in your document head to add this).

You can also rely on jQuery to calculate window width (assuming you are using a pixel value for minimum width) in the following example:

<script>
	$(document).ready(function(){
		$.inlineFootnotes({
			columnWidth: 960
		})
	});
</script>

This version also works cross browser, so long as your minimum window width is calculated using pixels and not rem or em or % units.