Jekyll on Github Pages: any way to add footnotes in Markdown?

Question

I've recently switched over to using Jekyll on Github Pages for my various blogs, and love that I can just push Markdown to Github and they handle the processing. I'd like to continue using it this way (rather than running Jekyll locally and just pushing the pre-generated site to Github), since the Github UI makes it easy to add and tweak posts if I'm not at my own machine.

There's just one thing I haven't been able to figure out: I can't get Markdown footnotes working. I'm using this style:

I bet you'd like more information about this sentence [^1].

[^1]: Well lucky for you, I've included more information in footnote form.

I did find one post (somewhere) that suggested enabling a footnotes extension for the redcarpet markdown processor, but this doesn't do it either:

markdown: redcarpet
redcarpet:
  extensions: ["footnotes"]

Is there any way to use Markdown footnotes without pre-generating the static site before pushing it to Github?

Collincolline

GitHub Markdown now (Sept. 2021) supports footnotes. But that would not necessarily translate into Jekyll GitHub pages. – Caliper

Answer 1

I use kramdown for markdown parsing and it handles footnotes nicely.

Change this line in your _config.yml file:

markdown: redcarpet

to:

markdown: kramdown

Wideawake

@BrockBoland I'm awfully fond of you too. – Wideawake

Unfortunately, kramdown can mean that code blocks generated by ``` (text here ``` dont' have newlines sorted properly, but I was able to resolve that with three tildas instead: ~~~ before and after the text. This is probably not an issue to most but I had a lot of code blocks like that so a change in the markdown style would have required me to edit a few of my posts. – Accommodate

Oddly I have markdown: kramdown in my _config.yml file but it never renders footnotes. Very odd. – Chimp

Answer 2

As of Jekyll 3.0.0, kramdown is the default Markdown processor, so the example in OP's question now works out of the box. The pattern is:

Some text[^1].

Some other text[^2].

The identifier in the square brackets does not have to be numeric[^my_footnote].

[^1]: Some footnote.
[^2]: Other footnote.

[^my_footnote]: This also works fine.

Update 3rd Jan. 2020:

• GitHub has its own markdown processor GFM, which is an extension of CommonMark. Both kramdown and GFM can be used to render GitHub Flavored Markdown.
• Footnotes are not yet supported by GitHub Flavored Markdown, which means the above examples do not render correctly in the GitHub code repository.
• Kramdown is still the default Markdown renderer for Jekyll. With kramdown, the above examples render correctly on sites based on GitHub Pages.

Vanzandt

Answer 3

Redcarpet

When you want to use redcarpet there seems to be no convenient solution right now. Although Redcarpet 3 supports footnotes with the syntax you've used, it is not included into Jekyll, because Redcarpet 3 removes Ruby 1.8 compatibility (source).

Solution 1: Use forked Redcarpet 2

See this solution by Jerod Santo:

Add a file called Gemfile to the root of your Jekyll folder with this content:

source "https://rubygems.org"

gem "jekyll"
gem "redcarpet", github: "triplecanopy/redcarpet"

or alternatively djui/redcarpet

Theny adjust your _config.yml to

markdown: redcarpet
redcarpet:
  extensions: [footnotes]

Solution 2: Fork Jekyll and include Redcarpet 3

I don't know what's the easiest way to do this. Comments are welcome.

Maruku

Seems to support footnotes (source, source).

Chalone

FYI: The extensions: [footnotes] works with Jekyll 2.2.0 (I don't know when it was added, though) – Papua

Would the original Github repo for redcarpet at vmg/redcarpet not be the best source to point to? – Commercialize

Answer 4

I found that plugin for jekyll Github orangejulius/jekyll-footnotes. May it solve the issue.

Also I read just today an blog post that Github improves the footnotes.

Alisun

Yes, that is the post I reference in https://mcmap.net/q/87100/-how-to-add-footnotes-to-github-flavoured-markdown – Caliper