Goldmark: How to configure the footnote anchor prefix?

[shaform]

When we use footnotes in an article, the anchor links generated would be #fn:1, #fn:2, etc. However, this causes problems on the index page because there are multiple articles using footnotes. How could we avoid this problem?

It seems that the same problem has been discussed some years ago:

Footnote references are duplicated on list pages

Pages with a list of posts that contain footnotes break the footnote links. The problem is that each post’s footnote IDs are generated starting at 1. So two posts which footnotes on the same page will both use #fn:1 as their ID which breaks the footnote hyperlinks. The footnote IDs should be unique to the post. Maybe a hash of the footnote number + the permalink URL or similar. If this doesn’t make sense I can put together a quick example.

Do we already have a solution now?

Update 1: It seems that if using blackfriday as the markdown renderer, the links generated would not be fn:1 and fn:2, but instead it would be the reference id used in the article. In this case, it’s easy to avoid the name clashes by using unique names. However, it is unclear whether we could achieve the same thing with the default goldmark renderer.

[alexandros]

Hello @shaform

I have changed the title of the topic to better reflect the question at hand:

How can we configure the footnoteAnchorPrefix in Goldmark like it is possible in Blackfriday to avoid footnote ids that clash with each other on list pages?

Unfortunately I also have no answer to your question.

As per the Goldmark README they make use of the PHP Markdown Extra: Footnotes library and on its documentation there appear to be options for customizing the footnote anchor id prefix.

However I am not aware if it is possible to configure in Hugo at the moment.

Perhaps the others know more. Or perhaps this should be posted as a feature request on Hugo’s GitHub issues tracker.

[shaform]

Thanks! I checked the code of goldmark, it seems that this feature has not been implemented so I guess I would post this as a feature request on goldmark’s GitHub issues page first. After it is implemented, I would post it as a feature request on Hugo’s GitHub issues page.

[jmooring]

Related:

• https://github.com/gohugoio/hugo/issues/7508
• https://github.com/yuin/goldmark/issues/92
• https://discourse.gohugo.io/t/does-goldmark-support-namedfootnotes/26727

[shaform]

Thanks! Didn’t notice these. It seems that it’s likely that support for non-numeric footnotes would not be added to goldmark because it’s not a priority for goldmark to be compatilibity with blackfriday.

However, the fn_id_prefix or footnoteAnchorPrefix config option does exist in the PHP Markdown, so maybe the author would be willing to implement this. I’ve created an issue for this: https://github.com/yuin/goldmark/issues/161

[alexandros]

Right I was not aware of all the background either. Thank you @jmooring for posting all these links.

@shaform and anyone else.

There is a manual way to use footnotes with unique IDs in Hugo.

I’ve used it at some point because I needed to display footnotes at the end of a text block and not at the end of a HTML page.

The concept is kind of simple.

1. Define a custom footnote shortcode under /layouts/shortcodes/footnote.html:

<sup class="footnote-ref" id="{{ .Get 0 }}fnref:-"><a href="#{{ .Get 0 }}fn:-">*</a></sup>

2. Define a custom citation shortcode in a similar PATH as above:

<li id="{{ .Get 0 }}fn:-">{{ .Get 1 }}<a class="footnote-return" href="#{{ .Get 0 }}fnref:-">^</a></li>

3. Define a custom footnotesList shortcode that will contain the nested citation shortcode along with the desired HTML:

<div class="footnotes">
<hr>
<ol>
{{ .Inner }}
</ol>
</div>

5. Then in a content file call the above like so:

Lorem Ipsum {{< footnote "ipsum" >}}

{{< footnotesList >}}
{{< citation "ipsum" "Ipsum maximus metus vel erat luctus, vitae imperdiet neque iaculis." >}}
{{< /footnotesList >}}

The above is tested and it works with multiple footnotes.

For my purposes I use an asterisk as a footnote reference. Obviously you can customize the shortcodes to use numbering or to output the HTML that suits your purposes.

Anyway, the bottom line is that while we wait for gohugoio/hugo/#7508 to be resolved there is a manual workaround to output footnotes without clashing IDs on list pages right now.

Of course for many footnotes the above may be an overkill.
But anyway you get the idea, it can always be improved.

[shaform]

@shaform

I would post this as a feature request on goldmark’s GitHub issues page first. After it is implemented, I would post it as a feature request on Hugo’s GitHub issues page.

Looks like goldmark’s author has implemented this feature, so I opened a feature request on Hugo’s GitHub issues page: https://github.com/gohugoio/hugo/issues/8045.