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?

Solution 1

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.

Solution 2

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>

Solution 3

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.

Solution 4

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.

Solution 5

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.

View more solutions

Comments

[Enrico Susatyo]

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.

[oldfartdeveloper]

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. <p> Bla bla <sup name="a1">[1](#f1)</sup>

[Matteo]

Thanks @oldfartdeveloper. It seems that both name and id work for README files on github.com.. haven't tested gists though.

[kayleeFrye_onDeck]

This is a nice middle-ground answer. It maintains clarify of intent without, IMO, too much bloat for formatting.

[milosa]

This doesn't generate a list of links at the end of your document though. Like on Wikipedia pages.

[Randall Whitman]

Using non-numeric references obviates the above-mentioned issue of maintaining sequential numeric references - Example [[TPL]](#TPL) ... #### Notes ... <a name="TPL">[TPL]</a> footnote template

[Guildenstern]

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.

[wardw]

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 . . .

[yegeniy]

This did not work in a GitHub Enterprise 2.8 markdown page

[sAguinaga]

should there be a colon after the square brackets?

[boweeb]

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.

[prashant]

This is not a footnote, this is a link.

[ruhong]

step #1 didn't work as a link on github markdown (Dec 2018).

[Seamus]

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), but this is THE answer afaic.

[Seamus]

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. Do you think this is a quirk in GitHub's rendering engine?

[Mars]

I have no idea, @Seamus. As I recall, there was a bit of trial and error when I was trying to figure it out.

[Seamus]

It's a clever solution. And yeah - that's still where we are today - trial and error :)

[conny]

@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. 😜

[Wolfson]

This works well in GitLab Flavored Markdown (GFM) as well. Although there is a built-in option 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).

[Bondolin]

This also works on Azure DevOps Server (Version Dev18.M170.6). I ended up using a <span> instead of a <b>, but that is merely a style preference.

[user90726]

Some flavors may restrict using HTML. In such a case, use characters from the Unicode superscript block: ⁰¹²³⁴⁵⁶⁷⁸⁹ (Chris already mentioned them, I just think they deserve more attention.)

[CMCDragonkai]

This doesn't seem to work on GitHub wikis.

[VonC]

@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: github.github.com/gfm

[Gerard Bosch]

Supported as per Sept. 2021: stackoverflow.com/a/69396272/6108874

[Gerard Bosch]

GitHub supports this as per Sept. 2021: stackoverflow.com/a/69396272/6108874

[Kevin]

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"

[VonC]

@Kevin Indeed. Let me know when you see those supported in GHE.