Site redesign: dealing with footnotes

I am now basically satisified with the way the site works now. But there was one itch I still needed to scratch. Footnotes. I don’t use them often, but I have come to like the way that the Tufte-Jekyll theme that I developed puts all the footnote type of content in the margins so they are easily accessible and readable as one is scrolling through the document. Even with a back link enabled, I think placing a footnote at the bottom of a long scrolling page of computer text is just goofy. However, I think cramming margin notes in this very clean looking site theme would be ugly.

The reason that I care about this is because when you encounter a footnote in a book, your eyes just go to the bottom of the page you are on and then return to the main flow of the text. But the arbitrarily long scroll-like layout of online text makes it difficult for a quick return to the text if the footnote information is at the very bottom of a very long page.

I decided to implement inline ‘footnotes’ that appear as a superscript symbol that will open when clicked on, and then close when the symbol is clicked again. Of course, these are not technically footnotes since they don’t sit at the foot of the document. But they serve the same purpose of presenting didactic asides that are not directly relevant to the immediate narrative flow. I borrowed the idea from the Tufte.css repo that my Tufte-Jekyll theme is based on. I am using the narrow screen mobile implementation of sidenotes and margin-notes.

Standard Github-style footnotes

The way that the Kramdown parser works in Jekyll is to take this markup:

Blah de blah de blah foonote goes here[^1], and then more
blah de blah blah Bob Loblaw Law Blog.

[^1]: And the actual footnote content goes here at the bottom with the same reference.

Blah de blah de blah foonote goes here¹, and then more blah de blah blah Bob Loblaw Law Blog.

That code gets massaged by Kramdown into this HTML:

<!-- The superscript link in the text is below -->

<sup id="fnref:1" role="doc-noteref"><a href="#fn:1" class="footnote" rel="footnote">1</a></sup>

<!-- and the footnote itself and the return link are turned into this: -->

<div class="footnotes" role="doc-endnotes">
  <ol>
    <li id="fn:1" role="doc-endnote">
      <p>And the actual footnote content goes here at the bottom with the same reference. 
          <a href="#fnref:1" class="reversefootnote" role="doc-backlink">&#8617;</a>
      </p>
    </li>
  </ol>
</div>

The Markdown approach is pretty easy, and a lot easier than typing in that tag hash you see in the rendered HTML above.

My first thought was to try to write a Javascript function that would troll through the tags on each page and look for footnotes and move them around to where I wanted them. But my not-very-sophisticated Javascript chops made that more daunting than I really wanted to spend time on.

Punt to Ruby

I decided to repurpose some of the custom Liquid tags that I wrote for the Tufte-Jekyll theme. I also made the decision that since these were inline footnotes, that I needed only one type of tag. So I dusted off my Rudimentary Ruby skills.

The tag structure

What I was aiming at was the ability to write something like this in my Markdown documents:

{% inlinenote 'arbitray-note-ID' 'Footnote - or inlne note text itself' %}

More typing than the pure Markdown approach, but much better than that godawful tag fest in the HTML above.

The Liquid tag plugin

I created a file in my Jekyll _plugins folder named inlinenote.rb. In this file I wrote the following Ruby code:

Module Jekyll
  class RenderInlineNoteTag < Liquid::Tag

    require "shellwords"

    def initialize(tag_name, text, tokens)
      super
      @text = text.shellsplit
    end

    def render(context)
      "<label for='#{@text[0]}' class='margin-toggle'> &#8853;</label><input type='checkbox' id='#{@text[0]}' class='margin-toggle'/><span class='inlinenote'>#{@text[1]} </span>"
    end
  end
end

Liquid::Template.register_tag('inlinenote', Jekyll::RenderInlineNoteTag)

This tag gets run each time my site is built in Jekyll. One note - if using the jekyll serve -w command to give real-time updates during the site-building process, it will necessitate quitting the jekyll server and restarting it to get the tag to be read by the jekyll build process.

Style it with SCSS

All that was left was to style the additional HTML that the tag plugin generates. I added the following SCSS to my SCSS file:

/*---- inlinenotes ---*/

.inlinenote{
  font-weight: 300;
  font-size:0.85rem;
  background-color: $alert-color; //this defines the 'open' toggle color
  margin:0;
  padding:1rem;
  border-radius: .5rem;
  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.12); 
  }
input.margin-toggle { display: none; }


label.margin-toggle { 
display: inline; 
color: $contrast-color; // this defines the color of the background of the opened inline note
margin-left:-.25rem;
position: relative;
top: -.35rem;
}
.inlinenote { display: none; }

.margin-toggle:checked + .inlinenote { 
   position: relative;
   display: block;
   float: left;
   left: 1rem;
   clear: both;
   width: 80%;
   margin-top: 1rem;
   margin-bottom: 1rem;
   margin-left:5%;
   margin-right: 15%;
 }
label { cursor: pointer; }

So now, I have inline footnotes that expand when the superscript symbol is clicked ⊕This is a bunch of random text that has nothing to do with anything whatsoever. That has never stopped me before however. Endless digressions are sometimes fun. And sometimes maddening, as anyone who has read David Foster Wallace will be willing to attest. . The footnote text pushes down all the text below it while it is open and the goes back to the regular document flow when the button is clicked again.

Conclusion

I am through fiddling with the site for a while. It does everything I need it to do and isn’t offensive to look at.