Skip to content

Update footnote guidance

Ashraf Khamis requested to merge update-footnote-guidance into master

What does this MR do and why?

Following this discussion, there seems to be an agreement on moving away from HTML because:

  • We cannot use relative links in HTML, which means our pipeline cannot check for possible broken links in footnotes.
  • Switching from Markdown to HTML is error-prone (see Examples of incorrectly rendered footnotes).

We should aim for a pure Markdown solution (see gitlab-docs#1766 (comment 1772209687) and !144843 (comment 1794563027)). The reason HTML was introduced is that our footnotes looked like the start of an ordered list. A simple and boring solution is to add **Footnotes:** at the beginning so the footnotes wouldn't be mistaken for a list.

I've also taken Marcel's feedback into account by making clear that we should use footnotes only when we cannot include the information in the table itself.

Examples of incorrectly rendered footnotes

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Screenshots or screen recordings

Screenshots are required for UI changes, and strongly recommended for all other merge requests.

Before After

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

Edited by Ashraf Khamis

Merge request reports