diff options
Diffstat (limited to 'doc/user/markdown.md')
| -rw-r--r-- | doc/user/markdown.md | 179 |
1 files changed, 140 insertions, 39 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index eaceeccc148..b8ed1c06324 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -124,8 +124,13 @@ to see the color chips next to the color code: ### Diagrams and flowcharts -You can generate diagrams and flowcharts from text by using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com). -You can also use [Kroki](https://kroki.io) to create a wide variety of diagrams. +You can generate diagrams from text by using: + +- [Mermaid](https://mermaidjs.github.io/) +- [PlantUML](https://plantuml.com) +- [Kroki](https://kroki.io) to create a wide variety of diagrams. + +In wikis, you can also add and edit diagrams created with the [diagrams.net editor](#diagramsnet-editor). #### Mermaid @@ -206,27 +211,44 @@ For more information, see the [Kroki integration](../administration/integration/ [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis). -```markdown -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +::Tabs -:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v: +:::TabTitle Rendered Markdown -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. +<!-- vale gitlab.Markdown_emoji = NO --> -If you're new to this, don't be :fearful:. You can join the emoji :family:. Just look up one of the supported codes. +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;padding:0;" title=":monkey:" alt=":monkey:"> 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;padding:0;" title=":star2:" alt=":star2:"> 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;padding:0;" title=":speech_balloon:" alt=":speech_balloon:">. Well we have a gift for you: -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. :thumbsup: -``` +<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;padding:0;" title=":zap:" alt=":zap:">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;padding:0;" title=":v:" alt=":v:"> + +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;padding:0;" title=":bug:" alt=":bug:"> 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;padding:0;" title=":speak_no_evil:" alt=":speak_no_evil:"> 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;padding:0;" title=":snail:" alt=":snail:"> 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;padding:0;" title=":birthday:" alt=":birthday:">. 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;padding:0;" title=":heart:" alt=":heart:"> you for that. -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: +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;padding:0;" title=":fearful:" alt=":fearful:">. 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;padding:0;" title=":family:" alt=":family:">. Just look up one of the supported codes. -<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"> +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;padding:0;" title=":thumbsup:" alt=":thumbsup:"> -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. +<!-- vale gitlab.Markdown_emoji = YES --> -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. +:::TabTitle Code -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"> +```markdown +Sometimes you want to :monkey: around a bit and add some :star2: to your +:speech_balloon:. Well we have a gift for you: + +:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v: + +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:. +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. :thumbsup: +``` + +::EndTabs #### Emojis and your operating system @@ -244,6 +266,8 @@ this font installed by default. <!-- vale gitlab.Spelling = YES --> +To learn more about adding custom emojis, see [Custom emojis](award_emojis.md#custom-emojis). + ### Front matter Front matter is metadata included at the beginning of a Markdown document, preceding @@ -357,6 +381,10 @@ _KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX. This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). +To prevent malicious activity, GitLab renders only the first 50 inline math instances. +The number of math blocks is also limited based on render time. If the limit is exceeded, +GitLab renders the excess math instances as text. + Math written between dollar signs with backticks (``$`...`$``) or single dollar signs (`$...$`) is rendered inline with the text. @@ -366,15 +394,15 @@ the language declared as `math` is rendered on a separate line: ````markdown This math is inline: $`a^2+b^2=c^2`$. -This math is on a separate line: +This math is on a separate line using a ```` ```math ```` block: ```math a^2+b^2=c^2 ``` -This math is on a separate line: $$a^2+b^2=c^2$$ +This math is on a separate line using inline `$$`: $$a^2+b^2=c^2$$ -This math is on a separate line: +This math is on a separate line using a `$$...$$` block: $$ a^2+b^2=c^2 @@ -383,23 +411,15 @@ $$ This math is inline: $`a^2+b^2=c^2`$. -This math is on a separate line: +This math is on a separate line using a ```` ```math ```` block: ```math a^2+b^2=c^2 ``` -This math is on a separate line: $$a^2+b^2=c^2$$ - -This math is on a separate line: - -$$ -a^2+b^2=c^2 -$$ - -This math is on a separate line: $$a^2+b^2=c^2$$ +This math is on a separate line using inline `$$`: $$a^2+b^2=c^2$$ -This math is on a separate line: +This math is on a separate line using a `$$...$$` block: $$ a^2+b^2=c^2 @@ -543,6 +563,58 @@ This example links to `<wiki_root>/miscellaneous.md`: [Link to Related Page](/miscellaneous.md) ``` +#### diagrams.net editor + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10. + +NOTE: +Use of the diagrams.net editor is not available on offline environments. + +In wikis, you can use the [diagrams.net](https://www.diagrams.net/) editor to create diagrams. You +can also edit diagrams created with the diagrams.net editor. The diagram editor is available in both +the Markdown editor and the content editor. + +##### Markdown editor + +To create a diagram in the Markdown editor: + +1. In the editor's toolbar, select **Insert or edit diagram** (**{diagram}**). +1. Use the diagrams.net editor to create the diagram. +1. Select **Save & exit**. + +A Markdown image reference to the diagram is inserted in the wiki content. + +To edit a diagram in the Markdown editor: + +1. Place the Markdown editor's text field cursor in a Markdown image reference +that contains the diagram. +1. Select **Insert or edit diagram** (**{diagram}**) in the Markdown editor. +1. Use the diagrams.net editor to edit the diagram. +1. Select **Save & exit**. + +A Markdown image reference to the diagram is inserted in the wiki content, +replacing the previous diagram. + +##### Content editor + +To create a diagram in the content editor: + +1. In the editor's toolbar, select **More options** (**{plus}**). +1. In the dropdown list, select **Create or edit diagram**. +1. Use the diagrams.net editor to create the diagram. +1. Select **Save & exit**. + +The diagram as visualized in the diagrams.net editor is inserted in the wiki content. + +To edit a diagram in the content editor: + +1. Select the diagram that you want to edit. +1. In the floating toolbar, select **Edit diagram** (**{diagram}**). +1. Use the diagrams.net editor to edit the diagram. +1. Select **Save & exit**. + +The selected diagram is replaced with an updated version. + ## GitLab-specific references GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference @@ -597,19 +669,44 @@ In addition to this, links to some objects are also recognized and formatted. So ### Show the issue, merge request, or epic title in the reference -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15694) in GitLab 14.6. +> - Support for issues, merge requests, and epics [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15694) in GitLab 14.6. +> - Support for work items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0. -To include the title in the rendered link of an issue, merge request, or epic, add a plus (`+`) +To include the title in the rendered link of an issue, work item, merge request, or epic, add a plus (`+`) at the end of the reference. For example, a reference like `#123+` is rendered as `The issue title (#123)`. URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are also expanded. -### Embedding metrics in GitLab Flavored Markdown +### Show the issue, work item or merge request summary in the reference + +> - Support for issues and merge requests [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/386937) in GitLab 15.10. +> - Support for work items [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390854) in GitLab 16.0. + +To include an extended summary in the rendered link of an issue, work item, or merge request, add a `+s` +at the end of the reference. Summary includes information about **assignees**, **milestone** +and **health status** of referenced item. + +For example, a reference like `#123+s` is rendered as +`The issue title (#123) • First Assignee, Second Assignee+ • v15.10 • Needs attention`. + +URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+s` are also expanded. + +### Embedding metrics Metric charts can be embedded in GitLab Flavored Markdown. Read [Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details. +### Embedding Observability dashboards + +You can embed GitLab Observability UI dashboards descriptions and comments, for example in epics, issues, and MRs. + +To embed an Observability dashboard URL: + +1. In GitLab Observability UI, copy the URL in the address bar. + +1. Paste your link wherever you want to embed your dashboard. GitLab Flavored Markdown recognizes the URL and displays the source. + ## Features extended from standard Markdown All standard Markdown formatting should work as expected in GitLab. Some standard @@ -656,13 +753,17 @@ you can quote that without having to manually prepend `>` to every line! ``` ->>> -If you paste a message from somewhere else - -that spans multiple lines, +<!-- +Use a standard blockquote here until https://gitlab.com/gitlab-org/gitlab/-/issues/390290 +gets properly fixed. The mixture of HTML comments and HTML tags +trigger this problem. +--> -you can quote that without having to manually prepend `>` to every line! ->>> +> If you paste a message from somewhere else +> +> that spans multiple lines, +> +> you can quote that without having to manually prepend `>` to every line! ### Code spans and blocks @@ -727,7 +828,7 @@ Tildes are OK too. If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). -GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax +GitLab uses the [Rouge Ruby library](https://github.com/rouge-ruby/rouge) 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 supported only in code blocks, so you can't highlight inline code. @@ -1594,7 +1695,7 @@ use `<br>` tags to force a cell to have multiple lines: | 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, -but they do not render properly on `docs.gitlab.com`. Note that these tasks will not save their +but they do not render properly on `docs.gitlab.com`. These tasks will not save their state when selected, like regular GitLab task lists. ```markdown |