Merge branch 'patch-56' into 'master'

Docs: note that footnote tags need not be numeric

See merge request gitlab-org/gitlab!22755

doc/user/markdown.md

@@ -773,17 +773,29 @@ do*this*and*do*that*and*another thing
 
 ### Footnotes
 
-Footnotes add a link to a note rendered at the end of a Markdown file:
+Footnotes add a link to a note that will be rendered at the end of a Markdown file.
+
+To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content.
+
+Regardless of the tag names, the relative order of the reference tags determines the rendered numbering.
 
 ```markdown
-You can add footnotes to your text as follows.[^1]
+A footnote reference tag looks like this:[^1]
+
+[^1]: This is the contents of a footnote.
 
-[^1]: This is my awesome footnote (later in file).
+Reference tags can use letters and other characters.[^footnote-note]
+
+[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) in your tag name until until an [upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
 ```
 
-You can add footnotes to your text as follows.[^1]
+A footnote reference tag looks like this:[^1]
+
+[^1]: This is the contents of a footnote.
+
+Reference tags can use letters and other characters.[^footnote-note]
 
-[^1]: This is my awesome footnote (later in file).
+[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) in your tag name until until an [upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
 
 ### Headers