Jekyll on Github Pages: any way to add footnotes in Markdown?
JekyllGithub PagesJekyll Problem Overview
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?
Jekyll Solutions
Solution 1 - Jekyll
I use kramdown for markdown parsing and it handles footnotes nicely.
Change this line in your _config.yml
file:
markdown: redcarpet
to:
markdown: kramdown
Solution 2 - Jekyll
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.
Solution 3 - Jekyll
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
Solution 4 - Jekyll
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.