Mild-Mannered Canadian Fury

Doug Stephen is Politely Peeved

Footnotes, Footnotify and Octopress

Thu, 26 Apr 2012 Ā«permalinkĀ»

As someone who spends a lot of time reading blogs, I’ve become a big fan of the citation style link. It keeps you in the moment and on task when you’re reading a long-form article instead of having to open a bunch of links in a new tab and try to remember what the context of the link was when you’re reading an article.

However, I’m an even bigger fan of using footnote links instead of parenthetical asides1. They keep the content on task while providing an easy way to explain or comment on a not immediately obvious idea.

Jekyll, and by extension Octopress, has built-in support for one of three Markdown processors: rdiscount, kramdown, and redcarpet. Octopress uses rdiscount by default, but rdiscount doesn’t offer support for Markdown Extra Footnote syntax, instead opting for the bog standard Markdown Citation Link. Coming from Tumblr, I’m a big fan of Markdown Extra’s Footnote syntax. Kramdown, however, does offer support for Markdown Extra footnotes.

Switching to Kramdown is easy; change the markdown: rdiscount configuration in your Octopress YAML config to kramdown. Make sure to enforce a kramdown version of at least 0.13.5. Earlier version of kramdown have a noted issue with processing block-level iframes in HTML. This is a big problem if you plan on doing anything like embedding YouTube or Vimeo videos. Modify your gemfile or install kramdown globally or do whatever it is you need to do in order to make sure your kramdown is up to date.

You may also want to tweak the vertical alignment and font-size on your super tags. I’m not sure if this is a result of a reset or intentional based on the base styles, but <sup> tags in Octopress seem to float barely an iota above the baseline and aren’t too much smaller than body text. I think this makes superscript elements much more intrusive than they are intended to be (unless you’re writing mathematical equations, but there are tools for that). Even if you don’t want to change the font-size on your superscripts, you should probably add a

  vertical-align: super;

somewhere in your stylesheets.

One thing to note when using kramdown instead of rdiscount (and the only thing that I needed to change in my writing habits) is that kramdown doesn’t automatically incorporate vertical whitespace when processing blockquotes. If you have a multiparagraph blockquote, you will need to put a > on each blank line in between paragraphs for the breaks to appear inside the quoted block instead of having the quote appear as multiple separate quotes. Additionally, kramdown does take a hair longer to process your markdown files in to HTML so if that’s a larger concern to you than having Markdown Extra style footnotes, then stick with rdiscount.

Great, so now you’ve switched to kramdown and you have footnotes. But maybe jumping about between anchors on a page isn’t your idea of fun. That’s where the amazing Footnotify plugin comes in to play. Not only a plugin, Footnotify is also available as JavaScript library with no external dependencies, making it a feature that anyone can provide on their blog. I had wanted to add the feature to this site until I saw in testing that for some reason the Footnotify popup looked hideous on the blog:

Footnotify Bad

That weird textured block on top is a non-starter. Additionally, in the past, that texture had overlapped the footnote number highlight and the small arrow indicator. I deactivated my fix in order to take that screenshot and it doesn’t look near as terrible as it did before. But that’s neither here nor there.

It turns out that the reason for this is that several Octopress styles use direct child selectors instead of classes or ID’s to apply background images to body root level <div> tags. Normally harmless, Footnotify injects its visual elements at the root level of the body tag, and so they were getting styled by the Octopress base theme. A tiny amount of CSS applied to these ID’s is all it takes to clean up the Footnotify divs to look like they were meant to look:

Footnotify Good

The styles are pretty simple:

  background-image: none;

  background-color: transparent;
  border: none;

Outside of that, I had to tweak some font styling to make it match the typefaces I use on the rest of the site. This, in turn, led me to have to tweak the arrow indicator slightly; this piece is cleverly created by two unicode right triangles squeezed together, so mucking around with your chosen font might make the gap between them visible. Tweak your font size and your letter spacing on the #footnotify_arrow element to get this correct.

This is only an issue if you are using the custom/_style.scss partial2 instead of modifying the base theme, since it is the base theme selectors that are interfering with Footnotify.

Now that I’ve figured this out, I have embedded Footnotify in to Mild-Mannered Canadian Fury for easy footnote reading. And if you want to do the same, you now have the tools at your disposal. Happy blogging!

  1. Or comma asides, or emdashes, or anything else, really.

  2. Which is how MMCF is themed.