kramdown Big Footnotes

Published in category Project and Programming
on Christian Mayer's Weblog.

I was searching for a different type of footnotes. The superscript footnote links are born to be overlooked. Big footnotes like [1] are always my favourite. Since I moved my blog to GitHub Pages all HTML pages are generated by Jekyll. This static website generator uses a Markdown parser named kramdown.

So let’s hack kramdown. First I cloned kramdown on GitHub and then cloned the fork to my local machine. Read more in GitHub’s HowTo Fork A Repo.

kramdown has for all cases tests. So I tried to run the tests before I add a new feature.

$ ruby test/run_tests.rb

But it failed:

Warning: you should require 'minitest/autorun' instead.
Warning: or add 'gem "minitest"' before 'require "minitest/autorun"'
  [...]/usr/lib/ruby/2.0.0/test/unit/assertions.rb:1:in `<top (required)>'
  test/run_tests.rb:12:in `<main>'
Testing test/testcases/block/01_blank_line/spaces.text                          FAILED
Testing test/testcases/block/01_blank_line/tabs.text                            FAILED
Testing test/testcases/block/02_eob/beginning.text                              FAILED
Testing test/testcases/block/02_eob/end.text                                    FAILED
Testing test/testcases/block/02_eob/middle.text                                 FAILED

The minitest gem is needed. Install minitest:

$ gem install minitest


Fetching: minitest-5.4.1.gem (100%)
Successfully installed minitest-5.4.1
Parsing documentation for minitest-5.4.1
Installing ri documentation for minitest-5.4.1
1 gem installed

But that wasn’t the point. I also updated from ruby 2.0.0p451 to ruby 2.1.1p76 using Homebrew. After that no more Ruby errors occured. I added the footnote_big option to lib/kramdown/converter/html.rb and lib/kramdown/options.rb of the kramdown library. That was easy. Finally it was possible to generate HTML from Markdown using big footnotes.

Pull Request is pending:

Update, 2014-09-11 17:09: Today I spent the whole noon and afternoon to install the exact dependency versions for Jekyll. Yesterday I also created a Bigfootnotes Plugin for Jekyll. Manipulating the HTML after it has been generated by the original HTML converter is a shitty workaround. However, the plugin works fine - on my local machine. But not on GitHub Pages. There are no plugins allowed on GitHub Pages due to security restrictions. But anyway, it’s also shitty because you can’t use multiple Markdown plugins for Jekyll at the same time. Maybe someone wants to use Kramdown with Pygments and the Bigfootnotes plugin. That’s not possible because like mine also the Kramdown with Pygments plugin is a subclass of Kramdown::Converter::Html. I asked the creator of kramdown, Thomas Leitner, to add the Big Footnotes feature.

Update, 2014-09-12 11:51: Thomas Leitner declined my pull request:

As per our e-mail conversation, this option doesn’t make sense for kramdown itself because it is a HTML output style change. If another person doesn’t like big footnotes, but small footnotes there would be a need for yet another option. Or if the footnote list should be a description list. Or …

I defined the default value for footnote_big to false. So this feature is for persons who like big footnotes. They must explicitly change the default settings, like any other default settings if you doesn’t like the default.

I have seen webpages with superscript footnotes, I have seen webpages with big footnotes. But I have never seen footnotes starting at number 2 or higher. They always start to count with number 1. Nobody starts their footnote at number 2. Or 3. Or 4. Or 97… So the footnote_nr option doesn’t make sense too. This option can be used to specify the number that is used for the first footnote. describes this option. But why should anybody ever would let their numbers to start at 2 instead of 1?

More Resources

Recent Posts

About the Author

Christian is a professional software developer living in Vienna, Austria. He loves coffee and is strongly addicted to music. In his spare time he writes open source software. He is known for developing automatic data processing systems for Debian Linux.