GitHub-Style Footnotes

[DerDrodt]

This PR adds the option of rendering footnotes at the bottoms in GitHub-Style, based on the implementation of notriddle.

Closes #1285.

For instance, the following markdown

### Footnotes

Footnote 1 link[^first].

Footnote 2 link[^second].

Duplicated footnote reference[^second].

[^first]: Footnote **can have markup**.

[^second]: Footnote text.

Gets rendered to:

<h3 id="footnotes">Footnotes</h3>
<p>Footnote 1 link<sup class="footnote-reference" id="fr-first-1"><a href="#fn-first">[1]</a></sup>.</p>
<p>Footnote 2 link<sup class="footnote-reference" id="fr-second-1"><a href="#fn-second">[2]</a></sup>.</p>
<p>Duplicated footnote reference<sup class="footnote-reference" id="fr-second-2"><a href="#fn-second">[2]</a></sup>.</p>
<hr><ol class="footnotes-list"><li id="fn-first" class="footnote-definition">
<p>Footnote <strong>can have markup</strong>. <a href="#fr-first-1">↩</a></p>
</li>
<li id="fn-second" class="footnote-definition">
<p>Footnote text. <a href="#fr-second-1">↩</a> <a href="#fr-second-2">↩2</a></p>
</li>
</ol>

This style is disabled by default and can be turned off via the markdown.bottom_footnotes option in the config.toml.

[Keats]

Can you clean up the commit history?

[DerDrodt]

Can you clean up the commit history?

Took some work but it's done. To make this easier for other contributors, you could merge the master branch into next.

[vbrandl]

I don't know, if this is out of scope for this change, but currently footnotes are generated like this:

<div class="footnote-definition" id="bar"><sup class="footnote-definition-label">1</sup>
  <p>baz</p>
</div>
<div class="footnote-definition" id="baz"><sup class="footnote-definition-label">2</sup>
  <p>lul</p>
</div>

I would like to render successive footnotes in a box, which is currently not possible. Is it possible to change the generated HTML to wrap successive footnotes inside a div with a CSS class to allow styling around a list of footnotes?

<div class="footnotes-list">
  <div class="footnote-definition" id="bar"><sup class="footnote-definition-label">1</sup>
    <p>baz</p>
  </div>
  <div class="footnote-definition" id="baz"><sup class="footnote-definition-label">2</sup>
    <p>lul</p>
  </div>
</div>

That way, the footnotes-list class can be used to draw a box around any list of footnotes.

[Drodt]

That way, the footnotes-list class can be used to draw a box around any list of footnotes.

I'm not a 100% sure, I understand you correctly, but all footnotes in this new style are wrapped in an <ol>. You can set a border on this and have your box.

[vbrandl]

I'm asking, if the old style of generating footnotes could be changed to wrap the footnotes in a div with class footnotes-list

[Drodt]

I'm asking, if the old style of generating footnotes could be changed to wrap the footnotes in a div with class footnotes-list

For that you should open a new Issue imo.

[vbrandl]

Ok, so it's out of scope, as expexted. I'll look into this.

Another question: shouldn't the Github style footnotes use the same CSS class names as the old footnotes?

[Keats]

Another question: shouldn't the Github style footnotes use the same CSS class names as the old footnotes?

Probably? If it makes sense

[Drodt]

Another question: shouldn't the Github style footnotes use the same CSS class names as the old footnotes?

I could do that, of course, but I don't think that's the best approach. As far as I can tell, quite a few markdown tools use the GitHub style with these classes. In my opinion, we should follow this more standard approach.

[Keats]

quite a few markdown tools use the GitHub style with these classes

do you have examples?

[DerDrodt]

Ah, sorry. I was thinking about a different thing and mixed up the classes you were referring to. I have now added the footnote-definition class.

[DerDrodt]

I also noticed that pulldown-cmark has added support for GitHub-style footnotes (raphlinus/pulldown-cmark#654). So the code changed by this feature can be removed if and when pulldown-cmark publishes a new release.

(The feature was added in June to the repository, the last version was published in May. It may take a while.)

[Keats]

Oh let's wait for that then if you don't mind, we would switch to it at the next release of pulldown-cmark anyway

[aterenin]

Just a note that it looks like the upstream PR was merged.

I would be very interested in having generated footnotes that use ol instead of div elements.

[nikhilweee]

Curious to know if this would be merged soon?

[Keats]

No, we'll update the library to add support when it's released

[dkales]

FYI, it seems that there are now new releases available: https://github.com/raphlinus/pulldown-cmark/releases/tag/v0.9.6.

[si14]

Unfortunately those releases don't include https://github.com/raphlinus/pulldown-cmark/pull/654 yet.

[kytta]

https://github.com/raphlinus/pulldown-cmark/releases/tag/v0.10.0 is now out and it has the relevant footnote issue included

[Keats]

Sweet! That's a long list of changes, anyone interested in doing a PR? I think there are quite a few changes to make to the current parser

[timonvo]

@Keats I've just sent https://github.com/getzola/zola/pull/2432 to update to the new pulldown_cmark v0.10.0 version, since I had already had most of the necessary changes ready in my personal fork.

[WaffleLapkin]

With https://github.com/getzola/zola/pull/2432 merged, can this move forward?

[Keats]

It should probably on its own PR, with an option in the config.toml that will enable the pulldown-cmark flag. Closing this PR as it's now outdated

[WaffleLapkin]

Is someone in the thread willing to make a new version of this PR?

[totikom]

I've started working on it, you can assign me to #1285.