It can be challenging to write about Markdown in Markdown, but Iâm going to try. The hard part is showing examples of the syntax without that syntax getting converted into HTML. For example, did you know that if you want to bold some text, you do it like this? Shit, that got bolded. Let me try again. You can do it **like this**. OK, great.
So what about footnotes? Adding a simple footnote is fairly straightforward: you put [^1] in the main flow of your prose to indicate that there is a footnote. Then you can add your footnote like this:
[^1]: My great footnote
Hereâs how that looks1.
John Gruber, the inventor of Markdown, recently published a recap of Appleâs recent iPhone 15 event which contained three footnotes. When I saw that one of them is three whole paragraphs, my eyes widened. You can do that???
If we look at the generated HTML, it looks like this:
<li id="fn2-2023-09-15">
<p>On the eve...</p>
<blockquote>
<p>Apple has also...</p>
</blockquote>
<p>Huaweiâs geopolitical travails...</p>
</li>
Nothing magical going on at all. Just some normal-looking HTML.
But, I wondered, how the hell do you represent that in Markdown? When I generate footnotes with Markdown, as soon as I finish the first paragraph, the footnote is done.
I happen to know that Daring Fireball has a trick, where you can append .text
to any URL and see the Markdown source code for that article. So I took a look at that articleâs source Markdown, and hereâs what I saw:
<li id="fn2-2023-09-15">
<p>On the eve...</p>
<blockquote>
<p>Apple has also...</p>
</blockquote>
<p>Huaweiâs geopolitical travails...</p>
</li>
Yep: the exact same thing. Heâs not using any special Markdown syntax to generate the footnotes, heâs doing it manually by writing HTML. And thatâs fair enough; itâs totally valid to include bits of HTML in your Markdown source.
But⊠does that mean that itâs not possible to have multi-paragraph footnotes in HTML-free Markdown? Well⊠unfortunately, itâs time that we start to get into some nuance (and a bit of drama).
I should note that Iâm referring to âMarkdownâ as though Markdown is one thing. Itâs not. Gruberâs original version of Markdown doesnât support footnotes at all (so itâs not a surprise that his blog implements them without any non-HTML syntax). There are many, many different implementations of Markdown. The one that I tend to use is called GitHub Flavored Markdown, which is the version of Markdown used in GitHub text fields. Itâs also the version of Markdown that I use to build this blog. So thatâs the one Iâll focus on today.
This diaspora of implementations can make it hard to find good information about what features you should expect to have access to. GitHub publishes a spec for GitHub flavored Markdown but it doesnât describe their implementation of footnotes. Elsewhere, they publish a doc on âBasic writing and formatting syntaxâ and its section on footnotes includes these two examples:
Here is a simple footnote[^1].
A footnote can also have multiple lines[^2].
[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
This is a second line.
Oh God, is that the best we can do? That seems to generate one paragraph, with <br />
tags breaking it up into multiple lines. Thatâs not really what I want.
But, clicking around, I found some reason for hope. The 2021 changelog post that introduced footnotes to GitHub embeds a gif that, hooray, includes a multi-paragraph footnote example, which looks like this:
Some text.[^bignote]
[^bignote]: Here's one with multiple paragraphs and code.
Indent paragraphs to include them in the footnote.
`{ my code }`
Add as many paragraphs as you like
As the gif looped and this little miracle flashed on the screen momentarily before flickering away again, I did my best to see what was there, and eventually the carousel looped around enough times that I got it. So thatâs easy enough: you can add more paragraphs to your footnote as long as you indent them (with four spaces). Easy.2 And hopefully this will actually continue to work, even though itâs barely documented.
I did tease a little drama, but Iâm actually not super invested in it. So, suffice it to say that Gruber is occasionally a bit salty about the various takes on Markdown that exist.
-
My great footnote ↩
-
Just to show it off here, Iâm doing another footnote, and this is the first paragraph of it.
and wow hereâs a blockquote and itâs still in the same footnote
And hereâs another paragraph thatâs still, magically, in the same footnote.
The blank lines between the paragraphs can just be blank, they donât need to have four spaces in them for no reason, donât worry. ↩