diff options
Diffstat (limited to 'doc/user/markdown.md')
| -rw-r--r-- | doc/user/markdown.md | 125 |
1 files changed, 59 insertions, 66 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 5e600b6e0d1..d20e9c7a30e 100644 --- a/doc/user/markdown.md +++ b/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,20 +209,20 @@ 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: ``` -Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: +Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you: -<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GitLab Flavored Markdown is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/public/-/emojis/2/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> -You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that. +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/app/assets/images/emoji/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/app/assets/images/emoji/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/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> +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"> #### Emojis and your operating system @@ -236,7 +234,7 @@ emojis where there is no support. <!-- vale gitlab.Spelling = NO --> -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) +On Linux, you can download [Noto Color Emoji](https://github.com/googlefonts/noto-emoji) to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has this font installed by default. @@ -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. @@ -811,10 +808,6 @@ the note content. Regardless of the tag names, the relative order of the reference tags determines the rendered numbering. -Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore -(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/24423) is -resolved. - <!-- Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test. --> @@ -823,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] -[^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. </code></pre> A footnote reference tag looks like this:[^1] @@ -837,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 @@ -897,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 @@ -938,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. --> @@ -955,7 +948,7 @@ Do not change to a reference style link.  -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. @@ -1133,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: @@ -1160,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). @@ -1182,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. @@ -1211,15 +1205,15 @@ Some text to show that the reference links can follow later. [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: @@ -1228,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. @@ -1236,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. @@ -1265,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: @@ -1364,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 @@ -1459,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, |