diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-18 21:09:35 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-18 21:09:35 +0300 |
commit | 5bfb8d1fad825eec90b0af688c7cd1b352c9056e (patch) | |
tree | 385411919c4186d11a769385ad8dafeef6cc36a7 /doc/user/markdown.md | |
parent | aaf59610548d9b0fd01acfd50e831cbe519ecba2 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/markdown.md')
-rw-r--r-- | doc/user/markdown.md | 134 |
1 files changed, 82 insertions, 52 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 29163f98fb4..882ded57684 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -45,10 +45,10 @@ in October 2018. You may have older issues, merge requests, or Markdown documents in your repository that were written using some of the nuances of GitLab's RedCarpet version -of Markdown. Since CommonMark uses a slightly stricter syntax, these documents -may now display a little differently since we've transitioned to CommonMark. +of Markdown. Since CommonMark uses slightly stricter syntax, these documents +might now appear a little differently since we have transitioned to CommonMark. -It is usually quite easy to fix. For example, numbered lists with nested lists may +It's usually quite easy to fix. For example, numbered lists with nested lists may render incorrectly: ```markdown @@ -119,7 +119,7 @@ changing how standard Markdown is used: > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors). -It is possible to have color written in HEX, RGB or HSL format rendered with a color +It's possible to have color written in HEX, RGB, or HSL format rendered with a color indicator. Supported formats (named colors are not supported): @@ -154,14 +154,14 @@ Color written inside backticks will be followed by a color "chip": ### Diagrams and flowcharts -It is possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com). +It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com). #### 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. If you are new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. +Visit the [official page](https://mermaidjs.github.io/) for more details. If you're new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: @@ -236,7 +236,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 will :heart: you for that. -If you are new to this, don't be :fearful:. You can easily 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 easily join the emoji :family:. All you need to do is to 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: ``` @@ -247,7 +247,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/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin: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"> patches. And 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"> 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">. People will <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"> you for that. -If you are 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">. You can easily 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">. 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/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily 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">. All you need to do is to 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"> @@ -345,7 +345,7 @@ The wrapping tags can be either curly braces or square brackets: --- -However the wrapping tags cannot be mixed: +However, the wrapping tags can't be mixed: ```markdown - {+ addition +] @@ -354,11 +354,24 @@ However the wrapping tags cannot be mixed: - [- deletion -} ``` +If your diff includes words in `` `code` `` font, make sure to escape each bactick `` ` `` with a +backslash `\`, otherwise the diff highlight won't render correctly: + +```markdown +- {+ Just regular text +} +- {+ Text with `backticks` inside +} +- {+ Text with escaped \`backticks\` inside +} +``` + +- {+ Just regular text +} +- {+ Text with `backticks` inside +} +- {+ Text with escaped \`backticks\` inside +} + ### Math > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math). -It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX). +It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX). Math written between dollar signs `$` will be rendered inline with the text. Math written inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered @@ -462,22 +475,35 @@ unordered or ordered lists: 1. [ ] Sub-task 1 1. [x] Sub-task 2 -### Table of Contents +### Table of contents -A table of contents can be added to a Markdown file, issue or merge request -description, or a wiki page, by adding the tag `[[_TOC_]]` on its own line. -It will be replaced with an unordered list that links to the various -headers. +You can add a table of contents to a Markdown file, wiki page, or issue/merge request +description, by adding the tag `[[_TOC_]]` on its own line. +It will appear as an unordered list that links to the various headers. ```markdown +This is an intro sentence to my Wiki page. + [[_TOC_]] + +## My first heading + +First section content. + +## My second heading + +Second section content. ``` +![Preview of an auto-generated TOC in a Wiki](img/markdown_toc_preview_v12_9.png) + +--- + ### Wiki-specific Markdown The following examples show how links inside wikis behave. -#### Wiki - Direct page link +#### Wiki - direct page link A link which just includes the slug for a page will point to that page, _at the base level of the wiki_. @@ -488,7 +514,7 @@ This snippet would link to a `documentation` page at the root of your wiki: [Link to Documentation](documentation) ``` -#### Wiki - Direct file link +#### Wiki - direct file link Links with a file extension point to that file, _relative to the current page_. @@ -499,10 +525,10 @@ it would link to `<your_wiki>/documentation/file.md`: [Link to File](file.md) ``` -#### Wiki - Hierarchical link +#### Wiki - hierarchical link A link can be constructed relative to the current wiki page using `./<page>`, -`../<page>`, etc. +`../<page>`, and so on. If this snippet was placed on a page at `<your_wiki>/documentation/main`, it would link to `<your_wiki>/documentation/related`: @@ -532,7 +558,7 @@ it would link to `<your_wiki>/documentation/main.md`: [Link to Related Page](../main.md) ``` -#### Wiki - Root link +#### Wiki - root link A link starting with a `/` is relative to the wiki root. @@ -560,7 +586,7 @@ If a functionality is extended, the new option will be listed as a sub-section. ### Blockquotes -Blockquotes are an easy way to highlight information, such as a side-note. It is generated +Blockquotes are an easy way to highlight information, such as a side-note. It's generated by starting the lines of the blockquote with `>`: ```markdown @@ -667,8 +693,8 @@ Tildes are OK too. GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the [Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers). -Syntax highlighting is only supported in code blocks, it is not possible to highlight -code when it is inline. +Syntax highlighting is only supported in code blocks, so it's not possible to highlight +code when it's inline. Blocks of code are fenced by lines with three back-ticks (```` ``` ````) or three tildes (`~~~`), and have the language identified at the end of the first fence: @@ -756,7 +782,7 @@ NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). -It is not usually useful to italicize just _part_ of a word, especially when you're +It's not usually useful to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. As a result, GFM extends the standard Markdown standard by ignoring multiple underlines in words, to allow better rendering of Markdown documents discussing code: @@ -793,7 +819,8 @@ do*this*and*do*that*and*another thing 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. +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. @@ -804,20 +831,23 @@ A footnote reference tag looks like this:[^1] Reference tags can use letters and other characters.[^footnote-note] -[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) -in your footnote tag name until an -[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. -``` +Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until +[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_] -A footnote reference tag looks like this:[^1] +[^this-name-has-w]: This won't be rendered, because the name contains "w". -[^1]: This is the contents of a footnote. +[^this-name-has_]: This won be rendered, because the name contains an underscore. + +``` Reference tags can use letters and other characters.[^footnote-note] -[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) -in your footnote tag name until an -[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. +Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until +[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_] + +[^this-name-has-w]: This won't be rendered, because the name contains "w". + +[^this-name-has_]: This won't be rendered, because the name contains an underscore. ### Headers @@ -849,7 +879,7 @@ the header to use it somewhere else. The IDs are generated from the content of the header according to the following rules: 1. All text is converted to lowercase. -1. All non-word text (e.g., punctuation, HTML) is removed. +1. All non-word text (such as punctuation or HTML) is removed. 1. All spaces are converted to hyphens. 1. Two or more hyphens in a row are converted to one. 1. If a header with the same ID has already been generated, a unique @@ -875,8 +905,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. +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. ### Horizontal Rule @@ -966,7 +996,7 @@ Here's a sample audio clip: > To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). -You can also use raw HTML in your Markdown, and it'll usually work pretty well. +You can also use raw HTML in your Markdown, and it will usually work pretty well. See the documentation for HTML::Pipeline's [SanitizationFilter](https://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default @@ -992,7 +1022,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau --- -It is still possible to use Markdown inside HTML tags, but only if the lines containing Markdown +It's still possible to use Markdown inside HTML tags, but only if the lines containing Markdown are separated into their own lines: ```html @@ -1023,7 +1053,7 @@ are separated into their own lines: </dd> </dl> -#### Details and Summary +#### Details and summary > To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). @@ -1034,7 +1064,7 @@ tags. This is especially useful for collapsing long logs so they take up less sc ```html <p> <details> -<summary>Click me to collapse/fold.</summary> +<summary>Click this to collapse/fold.</summary> These details <em>will</em> remain <strong>hidden</strong> until expanded. @@ -1046,7 +1076,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. <p> <details> -<summary>Click me to collapse/fold.</summary> +<summary>Click this to collapse/fold.</summary> These details <em>will</em> remain <strong>hidden</strong> until expanded. @@ -1062,7 +1092,7 @@ after the `</summary>` tag and before the `</details>` tag, as shown in the exam ````html <details> -<summary>Click me to collapse/fold.</summary> +<summary>Click this to collapse/fold.</summary> These details _will_ remain **hidden** until expanded. @@ -1076,7 +1106,7 @@ PASTE LOGS HERE <!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown will be fine in GitLab --> <details> -<summary>Click me to collapse/fold.</summary> +<summary>Click this to collapse/fold.</summary> These details <em>will</em> remain <b>hidden</b> until expanded. @@ -1084,10 +1114,10 @@ These details <em>will</em> remain <b>hidden</b> until expanded. </details> -### Line Breaks +### Line breaks A line break will be inserted (a new paragraph will start) if the previous text is -ended with two newlines, i.e. you hit <kbd>Enter</kbd> twice in a row. If you only +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 will be part of the same paragraph. This is useful if you want to keep long lines from wrapping, and keep them easily editable: @@ -1116,8 +1146,8 @@ in the *same paragraph*. GFM adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). -A paragraph is simply one or more consecutive lines of text, separated by one or -more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks). +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). If you need more control over line-breaks or soft returns, you can add a single line-break by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new @@ -1340,7 +1370,7 @@ Example: ### Superscripts / Subscripts -CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that +Currently, CommonMark and GFM don't support the superscript syntax ( `x^2` ) that Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts: ```html @@ -1353,7 +1383,7 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. ### Tables -Tables aren't part of the core Markdown spec, but they are part of GFM. +Tables are not part of the core Markdown spec, but they are part of GFM. 1. The first line contains the headers, separated by "pipes" (`|`). 1. The second line separates the headers from the cells, and must contain three or more dashes. @@ -1401,8 +1431,8 @@ to the sides of the "dash" lines in the second row. This will affect every cell [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27205) in GitLab 12.7. -If you're working in spreadsheet software (e.g. Microsoft Excel, Google -Sheets, Apple Numbers), you can copy from a spreadsheet, and GitLab will +If you're working in spreadsheet software (for example, Microsoft Excel, Google +Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab will paste it as a Markdown table. For example, suppose you have the following spreadsheet: |