When I sit in front of an old school, regular computer¹, writing happens in Vim. Mails, code, blogposts, my diploma thesis, ToDo-lists, comments on random web pages² - everything.

And I love Markdown. And footnotes³. So the usage of MultiMarkdown-footnotes is a natural fit.

There is no real standard for the notation, but most people tend to use numbers or words or a combination of these two. As long as the footnote marker is preceded by a caret (^) and enclosed by square brackets ([]) and the matching footnote reference starts at the beginning of a line and is followed by a colon (:), MultiMarkdown is a happy camper. The resulting Markdown-source is easy to read and really flexible:

1
2
3
4
5
6
7
8
9
10

This is an example text containig footnotes[^1]. These can be made of numbers
or almost any other character[^anotherfootnote]. 

Of course, one can use a combination[^fn5].

[^1]: This is a footnote...

[^anotherfootnote]: Therefore, this is also a footnote...

[^fn5]: This is also a footnote...

Trouble is, all these brackets and carets for the footnote links are kind of hard to type. The best practice for the footnote references is to keep them at the end of the file, so additional cursor movement is necessary. If you just want to insert a footnote as fast as possible and keep your writing flow, all this key pressing gets boring really soon.

vim-markdownfootnotes to the rescue

Luckily, I use Vim. Vim loves text automation. And Vim is used by lots of smart people like David Sanson who forked the venerable vimfootnotes, named it vim-markdownfootnotes and tweaked it for use with the extended Markdown markup as shown above.

The vim-markdownfootnotes plugin can easily be installed with Pathogen and defines two mappings:

1
2

<Leader>f    Insert new footnote 
<Leader>r    Return from footnote

From now on, you just type <Leader>f whenever you want to insert a footnote marker. The mapping works in normal and in insert mode which results in almost no friction while writing. This simple command inserts a footnote marker like [^1] after the cursor and a matching footnote reference like [^1]: gets inserted all the way down at the end of the file. Impressive, but the wonder does not stop here:

Vim opens a new buffer in a split window at the bottom of the current window and places your cursor right behind the empty space after the colon. This way you can just keep on typing your footnote and hit <Leader>r to close the split and return to the place in the main text where you left off. And you just keep on typing, leaving behind only a beautifully formatted MultiMarkdown footnote and no wasted thoughts.

It looks a lot like this:

The plugin also keeps track of the number of footnotes it inserted so the second footnote marker gets inserted as [^2], the third as [^3] and so on…

It’s a really good solution and includes some nice bells and whistles. If, for example, you don’t like the use of the default arabic numerals you are free to change the format by setting the variable vimfootnotetype to one of the following:

• arabic: 1, 2, 3…
• alpha: a, b, c, aa, bb…, zz, a…
• Alpha: A, B, C, AA, BB…, ZZ, A…
• roman: i, ii, iii… (displayed properly up to 89)
• Roman: I, II, III…
• star: *, **, ***…

Because we can. Crazy stuff. Totally cool if you think about it.

My footnote counter pet peeve

I installed the plugin in spring 2012 and slightly changed the sourcecode to use [^fn23] as footnote markup⁴ to make it more distinguishable from regular numbered Markdown reference style links. I kept on using it ever since, despite one minor gripe which kept on itching me:

The footnote counter only works for one session. Whenever I opened a file which already contained some footnotes, I had to check⁵ for the number of the last added footnote and use the FootnoteNumber command to set the counter to the correct starting point.

I usually write my blogposts in small chunks, so typing :FootnoteNumber 5 after finding out that the last footnote was [^fn4] was also kinda boring. And of course I always inserted a [^fn1] when footnotes were already present in the file before remembering I had to adjust the counter. So I had to undo the last footnote, close the split by hand, reset the counter and start again…

I don’t want to do this little footnote-counter-adjusting-dance every time I open a file. My computer should do this for me. I mean, seriously how hard can it be?

Luckily, another smart Vim-user named Nick Coleman, solved the problem for the automatic insertion of HTML-footnotes which are magnitudes harder to type than their Markdown counterparts. He wrote his own footnote.vim script which⁶ does not include fancy stuff like key mappings or splits but had a working footnote counter implemented in VimL.

So I did what every self respecting geek would do:

I ripped the code apart and changed the regular expression to match against my style of Markdown footnotes. The result worked fine on it’s own but I missed the easy writing flow of <Leader>f and <Leader>r.

Naturally, I forked vim-markdownfootnotes on Github and cobbled the counter code directly into the function s:VimFootnotes(appendcmd). Now, whenever I hit <Leader>f the script counts the occurences of the footnote references, adds 1 and sets the global variable g:vimfootnotenumber to the result.

The FootnoteNumber, FootnoteNumberRestore and FootnoteUndo functions are still present in the code, but whatever they set the variable to gets overridden by the automatic counter which, by the way, even works with non arabic numerals. So people who prefer their footnotes numbered with roman numerals or stars can also use this.

No more thinking about the current footnote counter, more thinking about my words. Excellent.

Sorting Markdown footnotes

Now, because I tend to edit my posts in small chunks it is not uncommon at all, that I insert a footnote somewhere in the text. Maybe even at the very beginning. This can lead to a situation like this⁷:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Well, the way they make shows is, they make one show. That show's called
a pilot[^fn2]. Then they show that show to the people who make shows, and on the
strength of that one show they decide if they're going to make more shows. Some
pilots get picked and become television programs. Some don't, become nothing.
She starred in one of the ones that became nothing.

Now that there is the Tec-9[^fn1], a crappy spray gun from South Miami. This gun is
advertised as the most popular gun in American crime. Do you believe that shit?
It actually says that in the little book that comes with it: the most popular
gun in American crime. Like they're actually proud of that shit[^fn3]. 

[^fn1]: This is a footnote concerning the Tec-9, it was the first that was written...

[^fn2]: This is the second footnote I added, it's marker appears in the text before the marker of the first footnote...

[^fn3]: This is the third footnote I added, it's marker is the last in the text...

The second footnote is added to the beginning of the text, 2 appears before 1. The footnote references are numbered 1, 2, 3 but the footnote markers are 2, 1, 3.

This is, and I may overreact here, totally wrong…

Markdown does not care a bit about the order in which the footnotes appear in the text. The text above and the following, nicely tidied up text render to the exact same HTML.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Well, the way they make shows is, they make one show. That show's called
a pilot[^fn1]. Then they show that show to the people who make shows, and on the
strength of that one show they decide if they're going to make more shows. Some
pilots get picked and become television programs. Some don't, become nothing.
She starred in one of the ones that became nothing.

Now that there is the Tec-9[^fn2], a crappy spray gun from South Miami. This gun is
advertised as the most popular gun in American crime. Do you believe that shit?
It actually says that in the little book that comes with it: the most popular
gun in American crime. Like they're actually proud of that shit[^fn3]. 

[^fn1]: This is the second footnote I added, it's marker appears in the text before the marker of the first footnote...

[^fn2]: This is a footnote concerning the Tec-9, it was the first that was written...

[^fn3]: This is the third footnote I added, it's marker is the last in the text...

So nobody but me would notice any difference. But really, this bothered me. So again, I turned to the Internet to see if I could find a solution for my problem. And sure enough, in a thread on the MultiMarkdown Google group I found a hint⁸ that the document converter Pandoc could do this by converting from Markdown to Markdown like this:

1

cat example.mmd | pandoc --from markdown --to markdown > tidied-example.mmd

Indeed, this works fine but strips my beloved fn-addition from each and every footnote… And I’m so used to my beloved fn-additions…

I considered diving into the source of Pandoc to fix this behaviour and learn some Haskell along the way but decided against it. I thought of formd, which I use to convert Markdown links from inline to reference style⁹ and wondered, why this fine software does not work with footnotes. After all, they are not that different from regular reference links, aren’t they?

Soon I found out that Seth Brown aka Dr. Bunsen altered the code of formd to ignore footnotes. As requested by Martin Kopischke and, ahem, me…

I tried to find out if I could alter the behaviour of formd to sort footnotes as effortless into a nice order as links. But my Python-fu was too weak.

With some more looking at the Internet I found a promising looking post by yet another Dr., Dr. Drang. He wrote a Python-script to tidy up Markdown reference links.

More importantly, he explained the inner workings of the script in great detail, so even I could figure out¹⁰ how this was supposed to work. Just like formd, the script made sure to exclude footnotes. I changed the two regular expressions to match against footnote markers and references and ignore regular markdown links. The inner logic remained the same and some more adjustments to the string replacement parts later the new sort_footnotes script worked surprisingly well. It looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

#!/usr/bin/python

import sys
import re

'''
Read a Markdown file via standard input and tidy the containing
Multimarkdown footnotes. The reference links will be numbered in
the order they appear in the text and placed at the bottom
of the file.

Based on "Tidying Markdown reference links" by Dr. Drang available at:

http://www.leancrew.com/all-this/2012/09/tidying-markdown-reference-links/

Do *not* place footnote reference links at the start of a line, bad things will
happen, your footnotes will be eaten by a grue.
'''

# The regex for finding footnote reference links in the text. 
link = re.compile(r'[^(?<=\n)](\[\^fn([\d]+)\])')

# The regex for finding the footnote labels with the text.
label = re.compile(r'(?<=\n)\[\^fn([\d]+)]:\s?(.*)')

def refrepl(m):
    # Rewrite reference links with the reordered link numbers. Insert the first
    # character from the footnote reference link right before the new link.
    return '%s[^fn%d]' % (m.group(0)[:1], order.index(m.group(2)) + 1)

# Read in the file and find all the footnote-links and -references.
text = sys.stdin.read()
links = link.findall(text)
labels = dict(label.findall(text))

# Determine the order of the footnote-links in the text. If a link is used
# more than once, its order is its first position.
order = []
for i in links:
    if order.count(i[1]) == 0:
      order.append(i[1])

# Make a list of the footnote-references in order of appearance.
newlabels = [ '[^fn%d]: %s \n' % (i + 1, labels[j]) for (i, j) in enumerate(order) ]

# Remove the old footnote-references and put the new ones at the end of the text.
text = label.sub('', text).rstrip() + '\n'*3 + '\n'.join(newlabels)

# Rewrite the footnote-links with the new footnote-reference numbers.
text = link.sub(refrepl, text)

print text

The script is also available in it’s own Github repository.

Like the original by Dr. Drang, sort_footnotes is by no means foolproof. In fact, it does not work with footnote links at the start of a line and fails horrible if one is found in a file. The alternate way to differentiate between footnote links and footnote references would have been the colon. I figured it is much more probable that a footnote link appears right before a colon, than it’s appearance at the start of a line. After all, footnotes should appear after words or, even better, sentences and not before them¹¹. Even stranger things might occur if two footnotes have the same number or if one marker misses it’s reference or vice versa. This kind of stuff should of course never happen if you use the automatic insertion of footnotes as described above but YMMV…

This script also does not work with roman numerals or stars so fans of these footnote markers will have to port the numeral converter from VimL to Python and insert it into my script¹²…

Because the script was designed to work via standard input it is easy to create a small Vim macro, assign a mapping like <Leader>fs and pipe the content of the current buffer through it. For good measure I also defined a <Leader>fx mapping to use formd and sort_footnotes in one fell swoop on the current buffer.

The mappings are defined in my .vimrc as follows:

1
2
3
4
5
6
7
8
9
10

" Use formd to transfer markdown from inline to reference links and vice versa
" Use the vim mark m to jump back to the position from where formd was invoked.
" see: http://drbunsen.github.com/formd/
nnoremap <leader>fr mm :%! ~/bin/formd -r<CR> `m :delmarks m<CR>
nnoremap <leader>fi mm :%! ~/bin/formd -i<CR> `m :delmarks m<CR>
" Sort footnotes into order of appearance
nnoremap <leader>fs mm :%! ~/bin/sort_footnotes<CR> `m :delmarks m<CR>
" Reformat with formd to reference style and sort the footnotes. The whole
" enchilada...
nnoremap <leader>fx mm :%! ~/bin/formd -r <bar> ~/bin/sort_footnotes<CR> `m :delmarks m<CR>

And this is pretty much it.

Without worrying about cursor movement, bracket typing and keeping footnote counters up to date it is much easier to type at the speed of thought. It is one mental barrier less when I jump into a draft for a 20 minute editing session after a long day. And the nicely ordered lists of links and footnotes at the end of my markdown source files make me feel all warm and cozy inside.