Update footnote guidance
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
-
https://docs.gitlab.com/ee/api/groups.html#list-a-groups-projects
Footnotes: 1. Order by similarity: Orders the results by a similarity score calculated from the provided `search` URL parameter. When using `order_by=similarity`, the `sort` parameter is ignored. When the `search` parameter is not provided, the API returns the projects ordered by `name`.
-
https://docs.gitlab.com/ee/user/group/import/#migrated-project-items
Footnotes: 1. Imported branches respect the [default branch protection settings](../../project/protected_branches.md) of the destination group, which can cause an unprotected branch to be imported as protected.
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.