Add latest changes from gitlab-org/gitlab@master

1 files changed, 17 insertions, 5 deletions

diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 2d7b9e17a40..9aa1849869b 100644
--- a/doc/user/markdown.md
+++ b/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