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?

GitHub Markdown now (Sept. 2021) [supports footnotes](https://stackoverflow.com/a/69396272/6309). But that would not necessarily translate into Jekyll GitHub pages. — VonC, Sep 30 '21 at 17:08

score 74 · Accepted Answer · answered Oct 22 '13 at 01:32

74

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

Change this line in your _config.yml file:

markdown: redcarpet

to:

markdown: kramdown

answered Oct 22 '13 at 01:32

Brian Willis

22,768
9
46
50

19

@BrockBoland I'm awfully fond of you too. – Brian Willis Oct 23 '13 at 21:35
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. – ComputerScientist May 15 '15 at 02:06
Oddly I have markdown: kramdown in my _config.yml file but it never renders footnotes. Very odd. – Alex White Jan 04 '23 at 23:18

Yi Ou · Answer 2 · 2021-01-03T10:16:33.107

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.

score 7 · Answer 3 · answered Jan 21 '14 at 18:26

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

FYI: The `extensions: [footnotes]` works with Jekyll 2.2.0 (I don't know when it was added, though) — docwhat, Aug 12 '14 at 03:43
Would the [original Github repo for redcarpet at vmg/redcarpet](https://github.com/vmg/redcarpet) not be the best source to point to? — sameers, Sep 05 '14 at 20:35

score 0 · Answer 4 · answered Sep 30 '21 at 18:47

0

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.

answered Sep 30 '21 at 18:47

KargWare

1,746
3
22
35

Yes, that is the post I reference in https://stackoverflow.com/a/69396272/6309 – VonC Sep 30 '21 at 19:18

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

4 Answers4

Redcarpet

Solution 1: Use forked Redcarpet 2

Solution 2: Fork Jekyll and include Redcarpet 3

Maruku

Linked