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
53
54
55
56
57
58
59
60
61
62
63
64
|
---
title: "Footnotes in Hugo and Goldmark"
categories: blog
abstract: How to add add footnotes to Hugo?
date: 2023-05-08T15:30:46+02:00
year: 2023
draft: false
tags:
- blog
- hugo
- goldmark
- footnote
- tutorial
---
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[^emoji], but are still decremental.
Yesterday[^first-footnote], I've added footnotes instead of a regular inline link for the first time. I was thinking about them since Fabien Sanglard[^fabien] 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.[^yeah]
[^first-footnote]: [Moving My RSS Reading to Emacs With Elfeed](/2023/moving-my-rss-reading-to-emacs-with-elfeed/)
[^emoji]: 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!
[^fabien]: [0X10 Rules](https://fabiensanglard.net/ilike/index.html). Fabien has one of the most interesting blogs I am aware of.
[^yeah]: Yeah!
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[^hugo], which uses Goldmark[^goldmark] as its Markdown parser. This gives us footnotes out of the box! We just need to enable it in the config:
[^goldmark]: [Goldmark on GitHub](https://github.com/yuin/goldmark)
```
[markup]
defaultMarkdownHandler = "goldmark"
[goldmark]
[Extensions]
footnote = true
```
[^hugo]: Hugo is a blazingly fast static site generator. You can learn more on [the official website](https://gohugo.io/) or read more [posts about Hugo](https://d-s.sh/tags/hugo/)
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[^aurelius]:
[^aurelius]: Mark Aurelius, Meditations, Book III. Taken from [Wikiquote](https://en.wikiquote.org/wiki/Marcus_Aurelius)
```
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[^stylize] or Java Script[^js]. Before Hugo moved to Goldmark, the parsing was handled by Blackfriday[^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.
[^js]: In my humble opinion, this usage is not enough to break user experience for people with disabled JS[^disabled-js], but that's just me.
[^stylize]: [Styling footnotes in Hugo](https://discourse.gohugo.io/t/footnote-styling/114/7)
[^disabled-js]: [Like me](https://d-s.sh/2023/its-near-impossible-to-use-noscript-but-the-future-is-bright/)
[^blackfriday]: [Blackfriday on GitHub](https://github.com/russross/blackfriday)
|
