Merge branch 'aqualls-20201027-markdown-page' into 'master'

Line edits to Markdown page

See merge request gitlab-org/gitlab!73212

doc/user/markdown.md

@@ -125,8 +125,6 @@ You can also use [Kroki](https://kroki.io) to create a wide variety of diagrams.
 
 #### Mermaid
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3.
-
 Visit the [official page](https://mermaidjs.github.io/) for more details. The
 [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) helps you
 learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve
@@ -211,7 +209,7 @@ Sometimes you want to :monkey: around a bit and add some :star2: to your :speech
 
 You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People :heart: you for that.
 
-If you're new to this, don't be :fearful:. You can join the emoji :family:. All you need to do is to look up one of the supported codes.
+If you're new to this, don't be :fearful:. You can join the emoji :family:. Just look up one of the supported codes.
 
 Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
 ```
@@ -222,7 +220,7 @@ Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/ma
 
 You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that.
 
-If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. All you need to do is to look up one of the supported codes.
+If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Just look up one of the supported codes.
 
 Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">
 
@@ -244,8 +242,6 @@ this font installed by default.
 
 ### Front matter
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6.
-
 Front matter is metadata included at the beginning of a Markdown document, preceding
 the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/),
 [Hugo](https://gohugo.io/content-management/front-matter/), and many other applications.
@@ -356,18 +352,18 @@ in a [code block](#code-spans-and-blocks) with the language declared as `math` i
 on a separate line:
 
 ````markdown
-This math is inline $`a^2+b^2=c^2`$.
+This math is inline: $`a^2+b^2=c^2`$.
 
-This is on a separate line:
+This math is on a separate line:
 
 ```math
 a^2+b^2=c^2
 ```
 ````
 
-This math is inline $`a^2+b^2=c^2`$.
+This math is inline: $`a^2+b^2=c^2`$.
 
-This is on a separate line
+This math is on a separate line:
 
 ```math
 a^2+b^2=c^2
@@ -408,16 +404,17 @@ To create a task list, follow the format of an ordered or unordered list:
 ### Table of contents
 
 A table of contents is an unordered list that links to subheadings in the document.
-
-To add a table of contents to a Markdown file, wiki page, issue request, or merge request
-description, add either the `[[_TOC_]]` or `[TOC]` tag on its own line.
-
-NOTE:
 You can add a table of contents to issues and merge requests, but you can't add one
-to notes or comments.
+to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line
+to the **Description** field of any of the supported content types:
+
+- Markdown files.
+- Wiki pages.
+- Issues.
+- Merge requests.
 
 ```markdown
-This is an intro sentence to my Wiki page.
+This sentence introduces my wiki page.
 
 [[_TOC_]]
 
@@ -579,7 +576,7 @@ by starting the lines of the blockquote with `>`:
 
 Quote break.
 
-> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
+> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
 ```
 
 > Blockquotes help you emulate reply text.
@@ -587,7 +584,7 @@ Quote break.
 
 Quote break.
 
-> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
+> This very long line is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
 
 #### Multiline blockquote
 
@@ -706,7 +703,7 @@ puts markdown.to_html
 
 ```
 No language indicated, so no syntax highlighting.
-s = "There is no highlighting for this."
+s = "No highlighting is shown for this line."
 But let's throw in a <b>tag</b>.
 ```
 ````
@@ -733,13 +730,13 @@ puts markdown.to_html
 
 ```plaintext
 No language indicated, so no syntax highlighting.
-s = "There is no highlighting for this."
+s = "No highlighting is shown for this line."
 But let's throw in a <b>tag</b>.
 ```
 
 ### Emphasis
 
-There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough,
+In Markdown, you can emphasize text in multiple ways. You can italicize, bold, strikethrough,
 and combine these emphasis styles together.
 Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown.
 
@@ -819,9 +816,9 @@ Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLink
 
 This reference tag is a mix of letters and numbers. [^footnote-42]
 
-&#91;^1]: This is the text inside a footnote.
+&#91;^1]: This text is inside a footnote.
 
-&#91;^footnote-42]: This is another footnote.
+&#91;^footnote-42]: This text is another footnote.
 </code></pre>
 
 A footnote reference tag looks like this:[^1]
@@ -833,9 +830,9 @@ Do not delete the single space before the [^1] and [^footnotes] references below
 These are used to force the Vale ReferenceLinks check to skip these examples.
 -->
 
- [^1]: This is the text inside a footnote.
+ [^1]: This text is inside a footnote.
 
- [^footnote-42]: This is another footnote.
+ [^footnote-42]: This text is another footnote.
 
 ### Headers
 
@@ -893,8 +890,8 @@ Would generate the following link IDs:
 1. `this-header-has-spaces-in-it-2`
 1. `this-header-has-3-5-in-it-and-parentheses`
 
-Note that the emoji processing happens before the header IDs are generated, so the
-emoji is converted to an image which is then removed from the ID.
+Emoji processing happens before the header IDs are generated. The
+emoji is converted to an image, which is then removed from the ID.
 
 ### Horizontal Rule
 
@@ -934,7 +931,7 @@ Reference-style (hover to see title text):
 </code></pre>
 
 <!--
-DO NOT change the name of markdown_logo.png. This is used for a test in
+DO NOT change the name of markdown_logo.png. This file is used for a test in
 spec/controllers/help_controller_spec.rb.
 -->
 
@@ -951,7 +948,7 @@ Do not change to a reference style link.
 
 ![alt text](img/markdown_logo.png "Title Text")
 
-In the rare case where you need to set a specific height or width for an image,
+In the rare case where you must set a specific height or width for an image,
 you can use the `img` HTML tag instead of Markdown and set its `height` and
 `width` parameters.
 
@@ -1129,8 +1126,8 @@ These details <em>remain</em> <b>hidden</b> until expanded.
 ### Line breaks
 
 A line break is inserted (a new paragraph starts) if the previous text is
-ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only
-use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the
+ended with two newlines, like when you press <kbd>Enter</kbd> twice in a row. If you only
+use one newline (select <kbd>Enter</kbd> once), the next sentence remains part of the
 same paragraph. Use this approach if you want to keep long lines from wrapping, and keep
 them editable:
 
@@ -1156,7 +1153,8 @@ in the *same paragraph*.
 
 #### Newlines
 
-GitLab Flavored Markdown adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/).
+GitLab Flavored Markdown adheres to the Markdown specification for handling
+[paragraphs and line breaks](https://spec.commonmark.org/current/).
 
 A paragraph is one or more consecutive lines of text, separated by one or
 more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks).
@@ -1178,25 +1176,25 @@ A new line due to the previous backslash.
 
 ### Links
 
-There are two ways to create links, inline-style and reference-style:
+You can create links two ways: inline-style and reference-style. For example:
 
 <!--
 Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
 -->
 
-<pre class="highlight"><code>- This is an [inline-style link](https://www.google.com)
-- This is a [link to a repository file in the same directory](index.md)
-- This is a [relative link to a readme one directory higher](../index.md)
-- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
+<pre class="highlight"><code>- This line shows an [inline-style link](https://www.google.com)
+- This line shows a [link to a repository file in the same directory](index.md)
+- This line shows a [relative link to a readme one directory higher](../index.md)
+- This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
 Using header ID anchors:
 
-- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
-- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
+- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
+- This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
 
 Using references:
 
-- This is a [reference-style link, see below][Arbitrary case-insensitive reference text]
+- This line shows a [reference-style link, see below][Arbitrary case-insensitive reference text]
 - You can [use numbers for reference-style link definitions, see below][1]
 - Or leave it empty and use the [link text itself][], see below.
 
@@ -1207,15 +1205,15 @@ Some text to show that the reference links can follow later.
 &#91;link text itself]: https://www.reddit.com
 </code></pre>
 
-- This is an [inline-style link](https://www.google.com)
-- This is a [link to a repository file in the same directory](index.md)
-- This is a [relative link to a README one directory higher](../index.md)
-- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
+- This line shows an [inline-style link](https://www.google.com)
+- This line shows a [link to a repository file in the same directory](index.md)
+- This line shows a [relative link to a README one directory higher](../index.md)
+- This line shows a [link that also has title text](https://www.google.com "This link takes you to Google!")
 
 Using header ID anchors:
 
-- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
-- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
+- This line links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
+- This line links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
 
 Using references:
 
@@ -1224,7 +1222,7 @@ The example below uses in-line links to pass the Vale ReferenceLinks test.
 Do not change to reference style links.
 -->
 
-- This is a [reference-style link, see below](https://www.mozilla.org/en-US/)
+- This line is a [reference-style link, see below](https://www.mozilla.org/en-US/)
 - You can [use numbers for reference-style link definitions, see below](https://slashdot.org)
 - Or leave it empty and use the [link text itself](https://www.reddit.com), see below.
 
@@ -1232,7 +1230,7 @@ Some text to show that the reference links can follow later.
 
 NOTE:
 Relative links do not allow the referencing of project files in a wiki
-page, or a wiki page in a project file. The reason for this is that a wiki is always
+page, or a wiki page in a project file. The reason: a wiki is always
 in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)`
 points the link to `wikis/style` only when the link is inside of a wiki Markdown file.
 
@@ -1261,14 +1259,14 @@ GitLab Flavored Markdown auto-links almost any URL you put into your text:
 <!-- vale gitlab.Spelling = YES -->
 ### Lists
 
-Ordered and unordered lists can be created.
+You can create ordered and unordered lists.
 
 For an ordered list, add the number you want the list
 to start with, like `1.`, followed by a space, at the start of each line for ordered lists.
-After the first number, it does not matter what number you use, ordered lists are
+After the first number, it does not matter what number you use. Ordered lists are
 numbered automatically by vertical order, so repeating `1.` for all items in the
 same list is common. If you start with a number other than `1.`, it uses that as the first
-number, and count up from there.
+number, and counts up from there.
 
 Examples:
 
@@ -1360,10 +1358,9 @@ Example:
 
 ---
 
-If the paragraph of the first item is not indented with the proper number of spaces,
+If the first item's paragraph isn't indented with the proper number of spaces,
 the paragraph appears outside the list, instead of properly indented under the list item.
-
-Example:
+For example:
 
 ```markdown
 1. First ordered list item
@@ -1455,13 +1452,13 @@ use `<br>` tags to force a cell to have multiple lines:
 ```markdown
 | Name | Details |
 | ---  | ---     |
-| Item1 | This is on one line |
+| Item1 | This text is on one line |
 | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately |
 ```
 
 | Name | Details |
 | ---  | ---     |
-| Item1 | This is on one line |
+| Item1 | This text is on one line |
 | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately |
 
 You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes,