How to add footnotes to GitHub-flavoured Markdown?

Question

I am just trying to add footnotes in my GitHub Gist, but it doesn't work:

Some long sentence. [^footnote]

[^footnote]: Test, [Link](https://google.com).

I am following this guide and I don't think I'm doing anything wrong. Can someone point out my mistake?

http://fletcher.github.io/peg-multimarkdown/ *Note: Currently, the Github wiki software supports Markdown, but not MultiMarkdown* Where is it documented that this is going to work? — ta.speot.is, Aug 30 '14 at 07:06
@ta.speot.is Ah, damn, so it wouldn't work? Is there any other way to do footnote in regular Markdown? — Enrico Susatyo, Aug 30 '14 at 07:07
@EnricoSusatyo Not in plain markdown, but for example [Pandoc supports it](http://johnmacfarlane.net/pandoc/README.html#footnotes) — mb21, Aug 30 '14 at 22:49
Interestingly, GitLab's markdown does support the `[^footnote]` syntax, even before it got [officially added to the documentation](https://gitlab.com/gitlab-org/gitlab-ce/commit/88ebb7b5e77307771da11e6e22a8c34f87d4a9de) — hmijail, Nov 01 '16 at 11:02
@hmijail you are referring to GitLab's footnote, not Github as the OP was asking. — Devy, Mar 08 '18 at 18:41
@Devy, yes, that's why I said "GitLab's markdown". Could still be useful, given that GitLab's flavour implementation seems to be based on the GitHub flavour, and that in general Markdown, its flavours and its implementations are an unholy mess. Summary: "just in case try this too". — hmijail, Mar 09 '18 at 21:29
@hmijail the question is specially titled "Github-flavored" markdown. — Devy, Mar 12 '18 at 16:31
@Devy I found hmijail comment very useful. I actually need to use footnote for MD file in GitLab repository. This Q was returned from duckduckgo and the correct answer for me I got from his comment. — jangorecki, Nov 24 '19 at 14:28
As of 2020, the exact syntax of footnotes **works**. You won't need to browse the answers for workarounds. — imrek, Jun 14 '20 at 09:04
@imrek I don't think this is fully supported yet. Just tried while commenting on an issue. It does not show up in the preview. — Ben Jones, Oct 26 '20 at 19:13
Can this question be considered a duplicate of https://meta.stackoverflow.com/q/258597? — Henke, Feb 01 '21 at 09:24
I can not believe that Github is making using Markdown so hard. — zyy, Jun 07 '21 at 18:03
Footnotes are now supported (Sept. 2021): See [my answer below](https://stackoverflow.com/a/69396272/6309) — VonC, Sep 30 '21 at 17:06
Values of "Supported" may vary, @VonC - for instance, I see the footnotes format working in .md file previews, but not in the github repository wiki feature. — Tom Hillman, Dec 07 '21 at 15:34
@TomHillman Yes, as commented in my answer below: wiki are indeed not supported yet. — VonC, Dec 07 '21 at 15:51

score 425 · Answer 1 · answered Apr 01 '15 at 06:29

425

Expanding a little bit on the previous answer, you can make the footnote links clickable here as well. First define the footnote at the bottom like this

<a name="myfootnote1">1</a>: Footnote content goes here

Then reference it at some other place in the document like this

<sup>[1](#myfootnote1)</sup>

answered Apr 01 '15 at 06:29

suryasankar

4,821
2
14
13

4

This is a nice middle-ground answer. It maintains clarify of intent without, _IMO_, too much bloat for formatting. – kayleeFrye_onDeck Feb 25 '16 at 19:45
3

Using non-numeric references obviates the above-mentioned issue of maintaining sequential numeric references - `Example [[TPL]](#TPL)` ... `#### Notes` ... `[TPL] footnote template` – Randall Whitman Oct 27 '16 at 17:07
7

Don't miss Part 2 in @Matteo's answer below. I was so chuffed with this answer (thanks) that i almost didn't bother to scroll down . . . – wardw Jan 06 '17 at 12:52
1

This works well in GitLab Flavored Markdown (GFM) as well. Although there is a [built-in option](https://docs.gitlab.com/ee/user/markdown.html#footnotes) available, I wanted the footnote's text to be rendered at a custom location (end of Section) instead of at the end of the whole file (built-in option). – Wolfson Nov 25 '20 at 10:43
2

GitHub supports this as per Sept. 2021: https://stackoverflow.com/a/69396272/6108874 – Gerard Bosch Dec 01 '21 at 15:07

score 278 · Accepted Answer · answered Aug 30 '14 at 16:33

278

GitHub Flavored Markdown doesn't support footnotes, but you can manually fake it¹ with Unicode characters or superscript tags, e.g. <sup>1</sup>.

¹Of course this isn't ideal, as you are now responsible for maintaining the numbering of your footnotes. It works reasonably well if you only have one or two, though.

answered Aug 30 '14 at 16:33

ChrisGPT was on strike

127,765
105
273
257

Thanks, I also like how other sites have clickable footnote links, but I guess this might be the only way to do it in GitHub. – Enrico Susatyo Sep 01 '14 at 06:20
14

You can also use regular numbers enclosed in square brackets[1], which is a pretty established convention for plaintext footnotes in my experience. (Gosh darnit why can’t I make line breaks in comments.) [1] I.e. like Pandoc Mandoc footnotes minus the caret. – Guildenstern Nov 01 '16 at 20:09
Some flavors may restrict using HTML. In such a case, use characters from the [Unicode superscript block](https://en.wikipedia.org/wiki/Unicode_subscripts_and_superscripts#Superscripts_and_subscripts_block): ⁰¹²³⁴⁵⁶⁷⁸⁹ (Chris already mentioned them, I just think they deserve more attention.) – user90726 Aug 22 '21 at 14:39

score 243 · Answer 3 · edited Oct 14 '15 at 21:31

243

Expanding on the previous answers even further, you can add an id attribute to your footnote's link:

 Bla bla <sup id="a1">[1](#f1)</sup>

Then from within the footnote, link back to it.

<b id="f1">1</b> Footnote content here. [↩](#a1)

This will add a little ↩ at the end of your footnote's content, which takes your readers back to the line containing the footnote's link.

edited Oct 14 '15 at 21:31

arcyqwerty

10,325
4
47
84

answered Aug 20 '15 at 13:37

Matteo

2,557
1
11
7

10

Adding a minor correction to @Matteo's response above, I had to use `name` instead of `id` in the call to the footnote. I.e.
`Bla bla ^[1](#f1)`
– oldfartdeveloper Sep 01 '15 at 10:41
4

Thanks @oldfartdeveloper. It seems that both `name` and `id` work for README files on github.com.. haven't tested gists though. – Matteo Sep 02 '15 at 13:27
7

For those who find this Q&A in circa 2020: This answer works on GitHub, PLUS it has the additional feature: *return-to-the-footnote-link-you-clicked*. I have found one [minor caveat (explained here)](https://github.com/seamusdemora/seamusdemora.github.io/blob/master/GFM_FootnotesWithReturnFeature.md), but this is **THE answer** afaic. – Apr 18 '20 at 05:09
This also works on Azure DevOps Server (Version Dev18.M170.6). I ended up using a `` instead of a ``, but that is merely a style preference. – Bondolin Aug 18 '21 at 17:33
1

Supported as per Sept. 2021: https://stackoverflow.com/a/69396272/6108874 – Gerard Bosch Dec 01 '21 at 15:05
But in any case, if you click to the refrence number, it is not leading to the in page citation. – bim Feb 25 '23 at 10:37

VonC · Answer 4 · 2021-12-07T15:52:50.513

30

Sept. 2021: Footnotes are here!

(Dec. 2021, as commented below, wiki README.md does not yet support footnotes)

"Footnotes now supported in Markdown fields"

Footnotes let you reference relevant information without disrupting the flow of what you're trying to say:
Here is a simple footnote[^1]. With some additional text after it.

[^1]: My reference.
You can now use footnote syntax in any Markdown field!

Footnotes are displayed as superscript links. Click them to jump to their referenced information, displayed in a new section at the bottom of the document:

Cf. Documentation.

edited Dec 07 '21 at 15:52

answered Sep 30 '21 at 17:06

VonC

1,262,500
529
4,410
5,250

2

This doesn't seem to work on GitHub wikis. – CMCDragonkai Oct 04 '21 at 04:45
1

@CMCDragonkai Indeed. Hopefully, GitHub will extend the support of that syntax to wikis. For now, the syntax isn't even added to the GFM spec: https://github.github.com/gfm/ – VonC Oct 04 '21 at 05:29
it would be nice if the docs said which version of Github (enterprise/onprem) this was enabled. GitHub Enterprise Server 3.2.1 does not have it for instance, but the PR comment box links to a page that says "footnotes are supported" – Kevin Dec 14 '21 at 19:41
@Kevin Indeed. Let me know when you see those supported in GHE. – VonC Dec 14 '21 at 21:30
It is not working actually – bim Feb 25 '23 at 10:28

score 19 · Answer 5 · answered Mar 04 '17 at 18:05

19

I wasn't able to get Surya's and Matteo's solutions to work. For example, "(#f1)" was just displayed as text, and didn't become a link. However, their solutions led me to slightly different solution. (I also formatted the footnote and the link back to the original superscript a bit differently.)

In the body of the text:

Yadda yadda<a href="#note1" id="note1ref"><sup>1</sup></a>

At the end of the document:

<a id="note1" href="#note1ref"><sup>1</sup></a>Here is the footnote text.

Clicking on the superscript in the footnote returns to the superscript in the original text.

answered Mar 04 '17 at 18:05

Mars

8,689
2
42
70

Interesting. You've used HTML where @Matteo used GFM. I was able to get his solution to work, but it required a [bit of fiddling](https://github.com/seamusdemora/seamusdemora.github.io/blob/master/GFM_FootnotesWithReturnFeature.md). Do you think this is a quirk in GitHub's rendering engine? – Apr 18 '20 at 05:16
I have no idea, @Seamus. As I recall, there was a bit of trial and error when I was trying to figure it out. – Mars Apr 18 '20 at 23:29
1

It's a clever solution. And yeah - that's still where we are today - trial and error :) – Apr 18 '20 at 23:37

score 15 · Answer 6 · edited Mar 06 '18 at 23:35

15

Although I am not aware if it's officially documented anywhere, you can do footer notes in Github.

Mark the place where you want to insert footer link with a number enclosed in square brackets, I.E. [1]
On the bottom of the post, make a reference of the numbered marker and followed by a colon and the link, I.E. [1]: http://www.example.com/link1

And once you preview it, it will be rendered as numbered links in the body of the post.

edited Mar 06 '18 at 23:35

David Moles

48,006
27
136
235

answered Aug 23 '16 at 21:13

Devy

9,655
8
61
59

5

This doesn't generate a list of links at the end of your document though. Like on Wikipedia pages. – milosa Sep 29 '16 at 15:59
should there be a colon after the square brackets? – sAguinaga Jun 08 '17 at 16:51
22

This is not a footnote, this is a link. – David Moles Mar 06 '18 at 23:35
step `#1` didn't work as a link on github markdown (Dec 2018). – ruhong Dec 28 '18 at 03:50
1

@DavidMoles I stumbled upon this SO post **because** I was looking for a way to include reference links as footnotes. So for those who google like me, this is the right answer even though it is the wrong question. – conny Nov 13 '20 at 10:06

score 14 · Answer 7 · answered Oct 09 '18 at 23:34

14

This works for me:

blablabla [<sup>1</sup>](#1) blablabla

footnotes: reference to blablabla <a class="anchor" id="1"></a>

answered Oct 09 '18 at 23:34

aerijman

2,522
1
22
32

score 13 · Answer 8 · edited May 12 '17 at 03:59

13

For short notes, providing an anchor element with a title attribute creates a "tooltip".

<a title="Note text goes here."><sup>n</sup></a>

Otherwise, for more involved notes, it looks like your best bet is maintaining named links manually.

edited May 12 '17 at 03:59

Pang

9,564
146
81
122

answered Nov 10 '16 at 17:25

Rich Traube

161
1
6

1

This did not work in a GitHub Enterprise 2.8 markdown page – yegeniy May 11 '17 at 17:04

Scott Gardner · Answer 9 · 2020-04-17T13:09:12.930

9

Here's a variation of Eli Holmes' answer that worked for me without using latex:

Text<span id="a1">[¹](#1)</span>

<span id="1">¹</span> Footnote.[⏎](#a1)<br>

Example

edited Apr 17 '20 at 13:09

answered Apr 17 '20 at 12:43

Scott Gardner

8,603
1
44
36

Eli Holmes · Answer 10 · 2018-03-14T22:31:26.573

I used a variant of Mateo's solution. I'm using this in Rmd files written in github flavored markdown (gfm) for a Jekyll powered website but the same Rmd files are being used to produce pdfs in various contexts. The Rmd files are math heavy and the math is displayed with MathJax on the website. So I needed a solution that works with gfm that is processed via Jekyll, works with pandoc->pdflatex, and is compatible with MathJax.

snippet from Rmd file (which is gfm)

Here is a paragraph with an footnote <span id="a1">[[1]](#f1)</span>.

Footnotes
=========

1. <span id="f1"></span> This is a footnote. [$\hookleftarrow$](#a1)

$\hookleftarrow$ is latex, which works for me since I always have MathJax enabled. I use that to make sure it shows up correctly in my pdfs. I put my footnotes in square brackets because superscript is confusing if I am putting a footnote on some inline math.

Here it is in action: https://eeholmes.github.io/posts/2016-5-18-FI-recursion-1/

These notes can be put anywhere in the Rmd. I am putting in a list at the end so they are technically endnotes.

Mildly tangential to the OP's question but ultimately I really like your "solution that works with gfm that is processed via Jekyll, works with pandoc->pdflatex, and is compatible with MathJax". Neat example. — boweeb, Feb 15 '18 at 15:08

score 8 · Answer 11 · answered Apr 27 '20 at 09:33

Although the question is about GitHub flavored Markdown, I think it's worth mentioning that as of 2013, GitHub supports AsciiDoc which has this feature builtin. You only need to rename your file with a .adoc extension and use:

A statement.footnote:[Clarification about this statement.]

A bold statement!footnote:disclaimer[Opinions are my own.]

Another bold statement.footnote:disclaimer[]

Documentation along with the final result is here.

score 0 · Answer 12 · answered Oct 25 '21 at 13:16

0

This one works on Kaggle notebook markdown:

Tell the story here.[<sup>[1]</sup>](#f1)

<span id="f1">[1]</span> Detail reference here.

answered Oct 25 '21 at 13:16

corngk

31
4

score 0 · Answer 13 · answered Jan 23 '22 at 09:37

0

I was looking for the same and I came up with the following, which is a footnote and opens the link in an external tab.

myfootnote^[Please see at: <a href="copylink" 
target="_blank">copylink</a> ]

answered Jan 23 '22 at 09:37

Seyma Kalay

2,037
10
22

How to add footnotes to GitHub-flavoured Markdown?

13 Answers13

"Footnotes now supported in Markdown fields"

Linked