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 emoji¹, but are still decremental.

Yesterday², I’ve added footnotes instead of a regular inline link for the first time. I was thinking about them since Fabien Sanglard³ 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.⁴

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 Hugo⁶, which uses Goldmark⁷ as its Markdown parser. This gives us footnotes out of the box! We just need to enable it in the config:

[markup]
  defaultMarkdownHandler = "goldmark"
  [goldmark]
    [Extensions]
      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 example⁸:

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 CSS⁹ or Java Script¹⁰. Before Hugo moved to Goldmark, the parsing was handled by Blackfriday¹¹ 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.