Footnote back-references

[lnicola]

It would be nice if the footnotes linked back to the source, like here.

[2mol]

I came here to open the same request, since I would really like this in Zola.

Has anything like this been implemented, or do you need help? I'm happy to offer to do it, maybe with some pointers to the right place in the code, since I'm not a Rust programmer.

[marcusklaas]

This is a tricky one. On the one hand, the value of back-references are immediately apparent.

On the other, implementing does not play well with the two-phase design of pulldown. One would have to go through all the events and capture the footnote references before you could emit a footnote itself. Usually, when footnotes are where they are supposed to be --at the bottom-- that's ok. But it's also valid to have footnotes at the top, like this:

[note]: we'll be referring to this later!

See the [^note] above.

Adding support for this not only brings some extra user complexity, but also a big hit to performance. The pulldown html parser is meant to provide a lean and performant reference implementation, which does not lend itself well to this feature.

The reality is that many users of the library do not write their own renderers and there seems to be an appetite for more features like this. We may have to re-evaluate whether we want to keep a lean implement or rather provide something more featureful.

[alerque]

Personally I use this exclusively for scanning to see what Markdown features are used where in source files; and it was hands down the best choice for that because of the raw speed. If things like this get implemented at all I would like to see them relegated to the renderer, not the parser. Personally I would have like to have just a parsing library with a separate renderer based on it, but in any even I would still appreciate being able to parse without being slowed down by features like this.

[2mol]

That makes sense, thanks for the thoughtful reply @marcusklaas . I don't have a clever suggestion, since I'm not familiar with the parser. But would you necessarily need to capture strictly valid back-references? If the renderer emits a #note link, and I don't have a target for it, that's sort of my problem, no? But maybe I don't have the right mental model, I'm assuming the parser wants to traverse the entire document just once.

I agree with both you and @alerque that taking a performance hit for this feature is not desirable.

[krtab]

Hi, I have hit the same issue and here are my thoughts on it: as @2mol said, if we don't care about generating dangling backlinks for footnotes that are never referenced, then this is simply a matter of adding the right id to the reference. Except that there is not guarantee that there will only be one reference to a given definition.

A possible solution is to generate "sub-ids" for each reference of a given footnote (storing them in a hashmap) and use them to generate multiple backlinks as Wikipedia does. The problem becomes that you'll only generate backlinks to reference that were above the definition.

What are you thoughts about this? I think that for the many indirect users of pulldown-cmark through zola or cobalt this is a quite needed feature, but it is not obvious which direction to take.

[GoldsteinE]

Slightly changing syntax of footnotes from:

Text[^footnote]

[footnote]: Text

to

Text[^footnote]

[^footnote]: Text

would allow to emit back-links inplace (if each footnote has only one associated link).

[chriskrycho]

For what it's worth, I experimented a bit with changing the rendering pass as part of trying to see how far I could get on the "standard" footnotes style with the current parser. (The answer is: pretty close, but as noted in the discussion in #20, the fact that footnotes are treated as single-block elements means a lot of existing footnotes out there won't parse.) As part of that I confirmed that you can quite easily build backlinks in a renderer given what pulldown-cmark already does.

While it's totally possible to end up with cases where you have a footnote reference with no definition or vice versa, that's an authoring concern (and a place where a renderer could choose to warn!). What's more, that's common in other Markdown implementation.

For example, if you drop this Markdown source into the pandoc demo (or just run pandoc --from markdown --to html5):

A paragraph of text. This demo has a valid footnote reference.[^valid] It also has a invalid footnote reference.[^invalid] And the document also has an orphaned definition, which is not referenced anywhere.

[^valid]: This one is valid.

[^orphan]: This is an orphan footnote definition.

This is the HTML it will generate:

<p>A paragraph of text. This demo has a valid footnote reference.<a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a> It also has a invalid footnote reference.[^invalid] And the document also has an orphaned definition, which is not referenced anywhere.</p>
<section class="footnotes" role="doc-endnotes">
<hr />
<ol>
<li id="fn1" role="doc-endnote"><p>This one is valid.<a href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
</ol>
</section>

There are two extra bits of data required to make that work the same way in a renderer:

• a list of footnote definitions which are actually referenced at least once (so e.g. a HashSet seems reasonable here)
• a similar list of footnote definitions which actually exist

If you pass both of those to a renderer along with the events, then it's straightforward when emitting the footnote events to do the same thing as pandoc and similar. The existing renderer doesn't support this, of course, and given it simply consumes an Iterator<Item = Event> it’s not clear to me that it could even be made to do so easily, but a fork of that renderer could do it easily enough.

---

This is actually quite encouraging for my purposes. The only serious blocker I see for conformance to the “standard” footnote format is having a scan/parse mode which supports multiple block children in the footnote and then having that lightly-tweaked renderer available (whether in-tree or not!).

While that unfortunately cannot be implemented backwards-compatibly with the current options (it changes the meaning of an indented block after a footnote definition block), I think it could be implemented with a new option. I am going to see if I can make progress on that. (Could be slow going: I don’t have a ton of time.)

[glhrmv]

Apologies if bumps are unwelcome, but I am just commenting to add that this would be a really good feature to have. Personally, I consider this a key requirement for any Markdown implementation. Footnotes should be in the foot of the document with back-links, regardless of where they're defined in the text itself.

[HanKruiger]

It seems like backlinks are also needed for the footnotes to render correctly in some (/many?) RSS readers: https://css-tricks.com/footnotes-that-work-in-rss-readers/

[flying-kestrel]

For reference, example/footnote_rewrite.rs shows a way to have footnotes behave how you might expect, with:

• Footnote bodies collected and appended at the end of the HTML output
• A list of backreferences inserted at the end of each footnote body

It's slightly annoying to need the extra wrapper code to achieve this, but not the end of the world.