Michał Sapka's website

Footnotes in Hugo and Goldmark

I was never a fan of inline links. They either disappear if the link is not stylized, or they break the flow of reading by being the first one you notice. They are not as eye-catching as emoji1, but are still decremental.

Yesterday2, I’ve added footnotes instead of a regular inline link for the first time. I was thinking about them since Fabien Sanglard3 mentioned how much he likes them, and I finally bit the bullet. I am sure I will overuse them for the foreseeable future, as with all my toys, but I will grow to use them wisely. For now, we are in this beautiful phase of relation where we don’t see each other flaws.4

Footnotes also solve my problem with adding comments. I constantly get sidetracked and insert some extra thoughts in the sentence. Not anymore, as that will also go a dedicated footnote. It’s there I am happy. It doesn’t pollute the main sentence, the reader is happy.

Footnotes in Hugo

This site is powered by Hugo6, which uses Goldmark7 as its Markdown parser. This gives us footnotes out of the box! We just need to enable it in the config:

  defaultMarkdownHandler = "goldmark"
      footnote = true

Now we are ready to use footnotes. To add one, add a reference [^ID] in text and then write the footnote:

[^ID]: text in markdown

One extremely cool thing about this is the way we can use IDs. Even though the ready footnote will be a 1-indexed list, we can use any ID in our markdown files. Nothing is stopping us from naming a footnote a footnote-link. Moreover, the footnote texts can be placed anywhere in the document - be it at the end of after the paragraph. Goldmark will process all of those, give them numerical IDs, and add them to the end of the text. We also have a ready validation, as reference without definition for the same ID will not be rendered as a link. An example8:

Choose what's best.—Best is what benefits me.[^translator]

[^translator]: Hays translation

This mechanism, however is imperfect, as we can’t easily customize how it’s displayed. To do any customization, we need to use CSS9 or Java Script10. Before Hugo moved to Goldmark, the parsing was handled by Blackfriday11 which allowed for more styling. Well, we’ve got what we’ve got.

But the bigger problem is the (lack of) uniqueness of generated IDs. Goldmark doesn’t know about Hugo, and Hugo generally doesn’t know what Goldmark is doing. The geneated IDs are unique for a single post, but not for the entire page. It makes my homepage broken since I put full content of each post there. I will most likely replace the homepage with simple list of posts, since I already plan a (yet another) overhaul of this site. For now, footnotes will be broken on the homepage. It will go nicely with the non-styled footnotes you see bellow.

  1. I really, really hate emojis, as they are the first thing you see. I know youngsters use them instead of text. I can agree that they have a place to convey emotions. But old-school emoticons work just as well while disappearing into the text. I can brag that this blog still uses 0 emojis! ↩︎

  2. Moving My RSS Reading to Emacs With Elfeed ↩︎

  3. 0X10 Rules. Fabien has one of the most interesting blogs I am aware of. ↩︎

  4. Yeah! ↩︎

  5. Like me ↩︎

  6. Hugo is a blazingly fast static site generator. You can learn more on the official website or read more posts about Hugo ↩︎

  7. Goldmark on GitHub ↩︎

  8. Mark Aurelius, Meditations, Book III. Taken from Wikiquote ↩︎

  9. Styling footnotes in Hugo ↩︎

  10. In my humble opinion, this usage is not enough to break user experience for people with disabled JS5, but that’s just me. ↩︎

  11. Blackfriday on GitHub ↩︎