Update footnotes to use superscript tags as links

Summary

Investigate and test using superscript tags (e.g. <sup>) as links that anchor to their corresponding numbered footnotes. This would improve navigation, especially for large tables or pages with multiple footnotes.

Context

Raised in a Slack discussion about footnote formatting in the GitLab docs. Previously, nanoc had rendering limitations that prevented this. Now that the docs site is built on Hugo, it may be possible to implement this with updates to the Hugo theme.

Goal

  • Test whether Hugo renders superscript tags as anchor links to footnotes correctly.
  • If not supported out of the box, explore what theme updates would be needed to make it work.

Additional info

From @marcel.amirault:

The issue with the Markdown standard is that all footnotes go to the bottom of the page, not the bottom of the table. So if we want to use the standard syntax, we'll need to customize our renderer, I believe.

For example, click on the two footnote examples at the end of this section: https://docs.gitlab.com/user/markdown/#footnotes

But I think it would make perfect sense to say that footnotes in a table go to the bottom of the > table, while footnotes in a page go to the bottom of the page.

I mean, even tables are not part of the Markdown spec, I don't see why some people want to adhere to it so closely, there are clearly gaps due to not considering all the needs when creating the standard. See Japanese, Korean and Chinese, where bold/italics do not work in all cases with the standard because it only assumes ascii (essentially).

Resources

Edited by Brendan Lynch