Markup: Enable Markdown footnotes extension

[nanoant]

Please add support for footnote extension that is supported by Redcarpet, Kramdown implementations. You just need to enable it on GitHub, so it is really minimal effort.

I recently was trying to use it and I was surprised it does not work on GitHub. It is really a pity because it works well for _reStructuredText_, yet rst does not support table cell alignment.

So I am stuck at my readme with ugly footnotes: https://github.com/nanoant/WebFrameworkBenchmark/blob/master/README.md

Referencing footnote[^1] in the text.

[^1]: Footnote definitions

[matteomenapace]

+1, it would be really useful!

See current hacks on this SO thread

[paregorios]

+1 this is a problem for, e.g., https://github.com/GitClassics/PugnaPorcorum/blob/master/Latin/Pugna/Pugna.md @cjmcnamara

[nanoant]

@gjtorikian @bkeepers Guys can you please have a look at this issue. It is really minimal effort to make it working (just config setting), but it will bring real benefit to GitHub's markdown.

[Stemby]

+1, please.

Thank you!

[gjtorikian]

We're discussing moving to a more formal standard like CommonMark. Realistically, we won't be introducing any more changes to the Markdown spec on our own. Sorry for any trouble this may cause.

[nanoant]

We're discussing moving to a more formal standard like CommonMark.

@gjtorikian So you are basically saying that not only there won't be footnotes on GitHub's markdowns, but also some existing features will stop working too because AFAIK GFM is not compatible entirely with CommonMark, eg. there are no tables.

So well, I wish you good luck then, your service will be definitely compatible with a shinny standard (that does not exist yet) even your users don't give a damn. And the benefit for that is.... ugh.. I don't know. I hope you know. Looks like history repeats itself, and CommonMark is next XHTML.

[gjtorikian]

When tables and other features are added (as specs or extensions) to the Commomark standard, we will look more seriously at switching. We won't be removing any existing GFM functionality, but at this time, we won't be adding any new ones either (like footnotes).

[gjtorikian]

I should add, also, that adopting a Commonmark standard is precisely intended to benefit users, so that they can expect the exact same syntax functionality when they visit GitHub or StackOverflow or Reddit or wherever. It's not a frivolous change.

[nanoant]

We won't be removing any existing GFM functionality, but at this time, we won't be adding any new ones either (like footnotes).

It is really disappointing that you don't acknowledge that footnotes are important and desired. This is also expressed at CommonMark discussion board.

I should add, also, that adopting a Commonmark standard is precisely intended to benefit users, so that they can expect the exact same syntax functionality when they visit GitHub or StackOverflow or Reddit or wherever. It's not a frivolous change.

I am not arguing with that. I understand that having common Markdown format is good. What I am arguing with is using CommonMark as an argument against enabling footnotes, because they are not a part of current draft, when in same time you (GitHub) are a member this standard committee. Finally telling us (users) that's for our benefit. Honestly this does not hold water.

If you want to do something for users benefit just enable them (because it is just simple switch in Kramdown), and in meantime make sure they make their way into the CommonMark standard too.

[codeblooded]

I'm a big fan of GitHub… My work is using BitBucket. Footnotes is the one feature that I really like over at BitBucket. However, they lack many things like project-wide search. It's great for citing references (in research documents that can be tracked) and it can offer a means of creating a more in-depth discussion without diverting the current flow of content. I do not see footnotes worthwhile in comments, pull requests, and issues. However, I definitely can see them in README's and documentation (on wiki)

Is it a deal breaker for GitHub? Absolutely not. Would it help (especially when migrating from BitBucket), yes.

[Stemby]

I agree: in my opinion you should integrate footnotes and, at the same time, drive the discussion on CommonMark for having footnotes implemented also in this standard.

Please reopen this issue.

Thank you!

[bwestergard]

Seconding Stemby. This would be a boon to anyone who writes in an academic style on Github.

[plm19]

Although it won't be found in Robert's Rules of Order ... I third the motion.

[dabrahams]

This still isn’t working for me.

[cceckman]

This issue has been around for ~11 months; in the intervening ~5 since its closure, CommonMark has not been adopted by GitHub. (And as far as I can tell from the repository, CommonMark itself hasn't been updated in several months.)

While the benefits of standardization are great (yay!), that's not a reason to not support this feature- not when it means ignoring your current users' requests for nearly a year. Another +1 for Stemby's comment.

@gjtorikian: Please take another look.

[gjtorikian]

Is it Commonmark season? I swear this is the third time this week I've linked to my own tweet: https://twitter.com/gjtorikian/status/715962596004749312

The last Commonmark bump was literally 10 days ago: https://github.com/jgm/CommonMark/tree/69f680f01216a87051b020d6706766c7eff52bc2

We are not going to introduce a new Markdown feature, then wait around until Commonmark decides what to do. I'd rather we move to Commonmark, and _then_ decide how to upgrade on the Markdown experience from there. If we move to include footnotes, we're not going to degrade that experience. And we really, really want to move to Commonmark first, because there's an obscene amount of corner cases that it solves.

I am sorry that that's probably not the answer you want, but it's the only answer I've got. We're not ignoring anything. We're trying to upgrade a component that powers every text area on this site.

[FranklinYu]

Seconding @gjtorikian. Moving to CommonMark before any change will prevent incompatible upgrades.

[kivikakk]

It's worth noting we are now on CommonMark: this comment is rendered by CommonMark, and we're transitioning all existing content to CommonMark (already mostly done! 🎉). We've put our own GFM-specific stuff (tables, stirkethru, etc.) on top of the reference cmark implementation so our user experience isn't degraded while still being spec-compliant, and so we're in a better position than we've ever been with regard to Markdown!

[foliovision]

Guys, CommonMark is lovely but we desperately need footnotes as well. Footnotes are pretty widely supported in offline Markdown applications now.

CommonMark also does not support footnotes (much to the chagrin of Stackoverflow users).

MultiMarkdown is the implementation which supports footnotes. But MultiMarkdown does not support strikethrough with two tildes so I'm not recommending it unconditionally (GitHub do support strikethrough).

Discount(which is what I have enabled in Marked 2) supports both footnotes and strikethrough. Discount is the only Markdown version which has full satisfied me after much testing. You can see the nice list of Markdown extensions, Discount supports at the top of that page, including:

• footnotes
• tables
• multileveled bulleted lists
• fenced code blocks

You cover all of those except footnotes and one more essential feature: strikethrough.

Brett Tepstra of nvAlt and Marked 2 fame considers it worth his while to support Discount along with MultiMarkdown so I'm not the only one out there keen on Discount.

Clean recommendation: Add the excellent working footnotes function from Discount. Dont touch anything else or make any other changes.

---

According to John MacFarlane's Babelmark 2, the most robust footnotes implementation is to be found in MultiMarkdown 5.1 and 6 (equally good). A simpler footnotes version passes Pandoc 1.19.2, PHP Markdown Extra 1.2.8, Maruku 0.7.3.beta1, MultiMarkdown 5.1.0 and 6, kramdown 1.2.0.

[xenithorb]

So... How do you do footnotes?

[BenjaminHolland]

@xenithorb

So... How do you do footnotes?

According to GitHub, you don't need them provided for you in markdown.

Fortunately, you can make them by adding html anchors and using Unicode to get you superscript/subscripts. You might be able to use ^/ as well. Elegant, it is not, but it fakes it well enough.

Poor performance. Octocat is crying.

[Ic3fr0g]

Follow this answer from the aforementioned SO thread

[RMBLRX]

So I've been trying the HTML solutions (from the SO thread, as mentioned above), and they don't seem to work properly in GitHub wikis. id doesn't seem to work at all, while name only works for going back up from the footnote to the reference and not for going down to the actual footnote. While I seem to remember this working previously in markdown files contained in the source (rather than the wiki), the behavior differs there, as well: The behavior of id and name are identical, but both behave the same way that name does in a wiki (can't link down to the footnote but can link back up to the reference).

Here's my approach:

<sup id="a1">[1](#f1)</sup>
 1. <small id="f1"> Some footnote.  </small> [↩](#a1)

I seem to remember this having worked before when found in the in the repo source, but it definitely works with Kramdown on a Jekyll site (as would [^1], if only that wouldn't break things on GitHub). So it seems that there's very little that has been truly standardized even within GFM, let alone between GFM and CommonMark, so it seems to me that GitHub could simply allow the emerging footnote standard (in the manner of [^1]) and perhaps advocate (explicitly or implicitly, I suppose) for making it standard in CommonMark.

I don't know, this just seems silly to me--footnotes are (or should be) so essential to all sorts of documentation or other sorts of publication and should not be treated as a hack in markdown of any kind.

[inwardmovement]

I'm also very interested in an implementation of footnotes extension, like in kramdown.

[keyvan-m-sadeghi]

I found a hack that works now and isn't as ugly as the alternatives IMO, with SUPERSCRIPT characters:

Here is a note[²].

...
At the bottom:

#### ² Note Two
[²]:#-note-two

Demo

[tpudlik]

Now that footnotes are supported as an extension in cmark-gfm (https://github.com/github/cmark-gfm/pull/64), it seems that resolving this issue is just a question of enabling the extension. Is that right?
If so, why is it a bad idea?

[kivikakk]

It's supported by the software, but a) it's not yet a part of the CommonMark spec, and more importantly, b) from a product design perspective we have not decided to include footmarks in Markdown-rendered content at GitHub. This isn't just a matter of flipping a switch -- it would take some thoughtful design to ensure it works consistently across the many different places Markdown is rendered at GitHub, and that's not my decision to make.

If you'd like this feature to be added, please reach out to the support team. It's the best way to voice your support for it.

[garbageslam]

It's 2020, please consider adding footnotes to github flavored markdown

[maiamcc]

++

[pbodnar]

Hm, I've just tested this and footnotes are rendered correctly on GitHub Pages (see an example) even though I removed this line from the __config.yml_:

markdown: kramdown

Also replacing it with:

markdown: GFM

... yields the same results.

So can somebody please tell me the current status of this thing?

BTW I know it doesn't belong here that much, but the documentation on markdown processors won't even tell you what is the default markdown used. While on the other hand, the very same page tries to explain you how to do a commit - why?

[robdockins]

It is INSANE that this has not been resolved, 5 years later.

[treier57lol]

GFM is really limiting without footnotes, this should be addressed.

[SubZeroX]

C'MON GUYS! It's 5 years now, where are the footnotes?

[HarryHenryGebel]

Such a sad fail that such a basic issue, not to mention required for even simple documents, has been brushed aside and ignored for five years.