diff options
Diffstat (limited to 'doc/user/markdown.md')
| -rw-r--r-- | doc/user/markdown.md | 690 |
1 files changed, 378 insertions, 312 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 01bd7ce0ba6..372442bb53f 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -25,13 +25,12 @@ When this list is rendered, it looks like this: - Dog - Turtle -These styles are **valid for GitLab only**. The [GitLab documentation website](https://docs.gitlab.com) -and the [main GitLab website](https://about.gitlab.com) use [Kramdown](https://kramdown.gettalong.org) instead. - -You should not view this page in the documentation, but instead [view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). +NOTE: +As this Markdown specification is **valid for GitLab only**, you should +[view these styles as they appear on GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md). -GitLab Flavored Markdown extends the [CommonMark specification](https://spec.commonmark.org/current/). -It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +We do our best to render the Markdown faithfully here, however the [GitLab documentation website](https://docs.gitlab.com) +and the [GitLab handbook](https://handbook.gitlab.com) use a different Markdown processor. ## Where you can use GitLab Flavored Markdown @@ -39,44 +38,58 @@ You can use GitLab Flavored Markdown in the following areas: - Comments - Issues +- Epics - Merge requests - Milestones - Snippets (the snippet must be named with a `.md` extension) - Wiki pages - Markdown documents inside repositories -- Epics You can also use other rich text files in GitLab. You might have to install a dependency to do so. For more information, see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup). ### Differences between GitLab Flavored Markdown and standard Markdown -GitLab uses standard CommonMark formatting. However, GitLab Flavored Markdown -extends standard Markdown with features made specifically for GitLab. +<!-- +Use this topic to list features that are not present in standard Markdown. +Don't repeat this information in each individual topic, unless there's a specific +reason, like in "Newlines". +--> -Features not found in standard Markdown: +GitLab Flavored Markdown consists of the following: + +- Core Markdown features, based on the [CommonMark specification](https://spec.commonmark.org/current/). +- Extensions from [GitHub Flavored Markdown](https://github.github.com/gfm/). +- Extensions made specifically for GitLab. + +All standard Markdown formatting should work as expected in GitLab. Some standard +functionality is extended with additional features, without affecting the standard usage. + +The following features are not found in standard Markdown: - [Color chips written in `HEX`, `RGB` or `HSL`](#colors) - [Diagrams and flowcharts](#diagrams-and-flowcharts) - [Emoji](#emoji) +- [Footnotes](#footnotes) - [Front matter](#front-matter) +- [GitLab-specific references](#gitlab-specific-references) - [Inline diffs](#inline-diff) - [Math equations and symbols written in LaTeX](#math) -- [Task Lists](#task-lists) +- [Strikethrough](#emphasis) - [Table of Contents](#table-of-contents) -- [Wiki specific Markdown](#wiki-specific-markdown) +- [Tables](#tables) +- [Task lists](#task-lists) +- [Wiki-specific Markdown](#wiki-specific-markdown) -Features [extended from standard Markdown](#features-extended-from-standard-markdown): +The following features are extended from standard Markdown: | Standard Markdown | Extended Markdown in GitLab | |---------------------------------------|---------------------------------------------------------------------------------------| -| [blockquotes](#blockquotes) | [multi-line blockquotes](#multiline-blockquote) | -| [code blocks](#code-spans-and-blocks) | [colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | -| [emphasis](#emphasis) | [multiple underscores in words](#multiple-underscores-in-words-and-mid-word-emphasis) | -| [headers](#headers) | [linkable Header IDs](#header-ids-and-links) | -| [images](#images) | [embedded videos](#videos) and [audio](#audio) | -| [line breaks](#line-breaks) | [more line break control](#newlines) | -| [links](#links) | [automatically linking URLs](#url-auto-linking) | +| [Blockquotes](#blockquotes) | [Multiline blockquotes](#multiline-blockquote) | +| [Code blocks](#code-spans-and-blocks) | [Colored code and syntax highlighting](#colored-code-and-syntax-highlighting) | +| [Headings](#headings) | [Linkable heading IDs](#heading-ids-and-links) | +| [Images](#images) | [Embedded videos](#videos) and [audio](#audio) | +| [Links](#links) | [Automatically linking URLs](#url-auto-linking) | ## Markdown and accessibility @@ -85,27 +98,25 @@ This content should be as accessible as possible to your audience. The following list is not exhaustive, but it provides guidance for some of the GLFM styles to pay particular attention to: -### Headings +### Accessible headings Use heading formatting to create a logical heading structure. The structure of headings on a page should make sense, like a good table of contents. Ensure that there is only one `h1` element on a page, that heading levels are not skipped, and that they are nested correctly. -### Tables +### Accessible tables To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering **N/A** for "not applicable" or **None**. -### Images and videos +### Accessible images and videos Describe the image or video in the `[alt text]`. Make the description accurate, succinct, and unique. Don't use `image of` or `video of` in the description. For more information, see [WebAim Alternative Text](https://webaim.org/techniques/alttext/). -## Features not found in standard Markdown - -The following features are not found in standard Markdown. +## Colors -### Colors +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors). Markdown does not support changing text color. @@ -132,9 +143,6 @@ display a color chip next to the color code. For example: - `HSLA(540,70%,50%,0.3)` ``` -[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors) -to see the color chips next to the color code: - - `#F00` - `#F00A` - `#FF0000` @@ -145,7 +153,7 @@ to see the color chips next to the color code: - `HSL(540,70%,50%)` - `HSLA(540,70%,50%,0.3)` -### Diagrams and flowcharts +## Diagrams and flowcharts You can generate diagrams from text by using: @@ -155,7 +163,9 @@ You can generate diagrams from text by using: In wikis, you can also add and edit diagrams created with the [diagrams.net editor](#diagramsnet-editor). -#### Mermaid +### Mermaid + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#mermaid). 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 @@ -220,24 +230,20 @@ graph TB end ``` -#### PlantUML +### PlantUML PlantUML integration is enabled on GitLab.com. To make PlantUML available in self-managed installation of GitLab, a GitLab administrator [must enable it](../administration/integration/plantuml.md). -#### Kroki +### Kroki To make Kroki available in GitLab, a GitLab administrator must enable it. For more information, see the [Kroki integration](../administration/integration/kroki.md) page. -### Emoji +## Emoji [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emoji). -::Tabs - -:::TabTitle Rendered Markdown - 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: <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:"> @@ -248,7 +254,7 @@ If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-f 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:"> -:::TabTitle Code +The above paragraphs in raw Markdown: ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your @@ -267,12 +273,10 @@ Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. :thumbsup: ``` -::EndTabs - -#### Emoji and your operating system +### Emoji and your operating system The previous emoji example uses hard-coded images. Rendered emoji -in GitLab may be different depending on the OS and browser used. +in GitLab might look different depending on the OS and browser used. Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based emoji where there is no support. @@ -280,14 +284,14 @@ emoji where there is no support. <!-- vale gitlab.Spelling = NO --> 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 +to get full native emoji support. Ubuntu 22.04 (like many modern Linux distributions) has this font installed by default. <!-- vale gitlab.Spelling = YES --> To learn more about adding custom emoji, see [Custom emoji](emoji_reactions.md#custom-emoji). -### Front matter +## Front matter 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/), @@ -349,7 +353,7 @@ $example = array( --- ``` -### Inline diff +## Inline diff [View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff). @@ -377,8 +381,8 @@ However, you cannot mix the wrapping tags: - [- deletion -} ``` -If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a -backslash <code>\</code>. Otherwise the diff highlight does not render correctly: +Diff highlighting doesn't work with `` `inline code` ``. If your text includes backticks (`` ` ``), escape +each backtick with a backslash <code>\</code>: ```markdown - {+ Just regular text +} @@ -388,7 +392,7 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre  -### Math +## Math > - LaTeX-compatible fencing [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21757) in GitLab 15.4 [with a flag](../administration/feature_flags.md) named `markdown_dollar_math`. Disabled by default. Enabled on GitLab.com. > - LaTeX-compatible fencing [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/371180) in GitLab 15.8. Feature flag `markdown_dollar_math` removed. @@ -397,7 +401,7 @@ backslash <code>\</code>. Otherwise the diff highlight does not render corre Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). _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 +This syntax also works in AsciiDoc wikis and files using `: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. @@ -445,7 +449,7 @@ $$ a^2+b^2=c^2 $$ -### Task lists +## Task lists > Inapplicable checkboxes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85982) in GitLab 15.3. @@ -453,12 +457,12 @@ $$ You can add task lists anywhere Markdown is supported. -- In issues, merge requests, and comments, you can select the boxes. +- In issues, merge requests, epics, and comments, you can select the boxes. - In all other places, you cannot select the boxes. You must edit the Markdown manually by adding or removing an `x` in the brackets. Besides complete and incomplete, tasks can also be **inapplicable**. Selecting an inapplicable checkbox -in an issue, merge request, or comment has no effect. +in an issue, merge request, epic, or comment has no effect. To create a task list, follow the format of an ordered or unordered list: @@ -480,28 +484,40 @@ To create a task list, follow the format of an ordered or unordered list:  -### Table of contents +To include task lists in tables, [use HTML list tags or HTML tables](#task-lists-in-tables). + +## Table of contents + +A table of contents is an unordered list that links to subheadings in the document. +You can add a table of contents to issues, merge requests, and epics, but you can't add one +to notes or comments. + +Add one of these tags on their own line to the **description** field of any of the supported +content types: <!-- -The following paragraphs use HTML to work around a Markdown bug. -Do not change it back to a Markdown backticks. +Tags for the table of contents are presented in a code block to work around a Markdown bug. +Do not change the code block back to single backticks. For more information, see https://gitlab.com/gitlab-org/gitlab/-/issues/359077. --> -<!-- vale gitlab.Uppercase = NO --> -A table of contents is an unordered list that links to subheadings in the document. -You can add a table of contents to issues and merge requests, but you can't add one -to notes or comments. Add either the `[[_TOC_]]` or <code>[TOC]</code> tag on its own line -to the **Description** field of any of the supported content types: -<!-- vale gitlab.Uppercase = YES --> -NOTE: -A table of contents renders also when you use <code>`[TOC]`</code>, regardless of being on its own line or not. -This behavior is unintended. For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). +```markdown +[[_TOC_]] +or +[TOC] +``` - Markdown files. - Wiki pages. - Issues. - Merge requests. +- Epics. + +NOTE: +A table of contents renders also when you use the TOC code in single square brackets, regardless of +being on its own line or not. +This behavior is unintended. +For more information, see [issue 359077](https://gitlab.com/gitlab-org/gitlab/-/issues/359077). ```markdown This sentence introduces my wiki page. @@ -519,11 +535,13 @@ Second section content.  -### Wiki-specific Markdown +## Wiki-specific Markdown The following topics show how links inside wikis behave. -#### Wiki - direct page link +When linking to wiki pages, you should use the **page slug** rather than the page name. + +### Wiki - direct page link A direct page link includes the slug for a page that points to that page, at the base level of the wiki. @@ -534,7 +552,7 @@ This example links to a `documentation` page at the root of your wiki: [Link to Documentation](documentation) ``` -#### Wiki - direct file link +### Wiki - direct file link A direct file link points to a file extension for a file, relative to the current page. @@ -545,7 +563,7 @@ it links to `<your_wiki>/documentation/file.md`: [Link to File](file.md) ``` -#### Wiki - hierarchical link +### Wiki - hierarchical link A hierarchical link can be constructed relative to the current wiki page by using `./<page>`, `../<page>`, and so on. @@ -578,7 +596,7 @@ it links to `<your_wiki>/documentation/main.md`: [Link to Related Page](../main.md) ``` -#### Wiki - root link +### Wiki - root link A root link starts with a `/` and is relative to the wiki root. @@ -594,7 +612,7 @@ This example links to `<wiki_root>/miscellaneous.md`: [Link to Related Page](/miscellaneous.md) ``` -#### diagrams.net editor +### diagrams.net editor > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322174) in GitLab 15.10. @@ -604,43 +622,54 @@ the plain text editor and the rich text editor. For more information, see [Diagrams.net](../administration/integration/diagrams_net.md). -##### Plain text editor +#### Plain text editor To create a diagram in the plain text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the plain text editor + (the button on the bottom left says **Switch to rich text editing**). 1. In the editor's toolbar, select **Insert or edit diagram** (**{diagram}**). -1. Use the diagrams.net editor to create the diagram. +1. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. A Markdown image reference to the diagram is inserted in the wiki content. To edit a diagram in the plain text editor: -1. Place the plain text editor's text field cursor in a Markdown image reference -that contains the diagram. -1. Select **Insert or edit diagram** (**{diagram}**) in the plain text editor. -1. Use the diagrams.net editor to edit the diagram. +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the plain text editor + (the button on the bottom left says **Switch to rich text editing**). +1. Position your cursor in the Markdown image reference that contains the diagram. +1. Select **Insert or edit diagram** (**{diagram}**). +1. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. A Markdown image reference to the diagram is inserted in the wiki content, replacing the previous diagram. -##### Rich text editor +#### Rich text editor To create a diagram in the rich text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the rich text editor + (the button on the bottom left says **Switch to plain text editing**). 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. Create the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 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 rich text editor: +1. On the wiki page you want to edit, select **Edit**. +1. In the text box, make sure you're using the rich text editor + (the button on the bottom left says **Switch to plain text editing**). 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. Edit the diagram in the [app.diagrams.net](https://app.diagrams.net/) editor. 1. Select **Save & exit**. The selected diagram is replaced with an updated version. @@ -657,54 +686,55 @@ version to reference other projects from the same namespace. GitLab Flavored Markdown recognizes the following: -| references | input | cross-project reference | shortcut inside same namespace | -|:----------------------------------------------------------------------------|:------------------------------|:----------------------------------------|:-------------------------------| -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | [`@all`](discussions/index.md#mentioning-all-members) | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| merge request | `!123` | `namespace/project!123` | `project!123` | -| snippet | `$123` | `namespace/project$123` | `project$123` | -| [epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | -| [iteration](group/iterations/index.md) | `*iteration:"iteration title"`| | | -| [vulnerability](application_security/vulnerabilities/index.md) <sup>1</sup> | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | -| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | -| label by ID | `~123` | `namespace/project~123` | `project~123` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | -| contact | `[contact:test@example.com]` | | | - -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. +| References | Input | Cross-project reference | Shortcut inside the same namespace | +| -------------------------------------------------------------- | ------------------------------ | --------------------------------------- | ---------------------------------- | +| Specific user | `@user_name` | | | +| Specific group | `@group_name` | | | +| Entire team | [`@all`](discussions/index.md#mentioning-all-members) | | | +| Project | `namespace/project>` | | | +| Issue | ``#123`` | `namespace/project#123` | `project#123` | +| Merge request | `!123` | `namespace/project!123` | `project!123` | +| Snippet | `$123` | `namespace/project$123` | `project$123` | +| [Epic](group/epics/index.md) | `&123` | `group1/subgroup&123` | | +| [Iteration](group/iterations/index.md) | `*iteration:"iteration title"` | | | +| [Vulnerability](application_security/vulnerabilities/index.md) | `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| Feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | +| Label by ID | `~123` | `namespace/project~123` | `project~123` | +| Label by name (one word) | `~bug` | `namespace/project~bug` | `project~bug` | +| Label by name (multiple words) | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| Label by name (scoped) | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| Project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| Milestone by name (one word) | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| Milestone by name (multiple words) | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| Commit (specific) | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| Commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| Repository file reference | `[README](doc/README.md)` | | | +| Repository file reference (specific line) | `[README](doc/README.md#L13)` | | | +| [Alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | +| [Contact](crm/index.md#contacts) | `[contact:test@example.com]` | | | For example, referencing an issue by using `#123` formats the output as a link to issue number 123 with text `#123`. Likewise, a link to issue number 123 is recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, add a leading backslash `\#123`. -In addition to this, links to some objects are also recognized and formatted. Some examples of these are: +In addition to this, links to some objects are also recognized and formatted. +For example: -- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` -- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. -- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. +- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, rendered as `#1234 (comment 101075757)` +- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, rendered as `#1234 (designs)`. +- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, rendered as `#1234[layout.png]`. ### Show the issue, merge request, or epic title in the reference > - 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, 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)`. +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. @@ -713,18 +743,23 @@ URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are al > - 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. +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. -To update the rendered references if the assignee, milestone, or health status changed, -edit the comment or description and save it. -For more information, see issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807). +To update the rendered references if the assignee, milestone, or health status changed: + +- Edit the comment or description and save it. + +Issue [420807](https://gitlab.com/gitlab-org/gitlab/-/issues/420807) tracks improving how these +references refresh. ### Embedding Observability dashboards @@ -733,16 +768,11 @@ You can embed GitLab Observability UI dashboards descriptions and comments, for To embed an Observability dashboard URL: 1. In GitLab Observability UI, copy the URL in the address bar. +1. Paste your link in a comment or description. GitLab Flavored Markdown recognizes the URL and displays the source. -1. Paste your link wherever you want to embed your dashboard. GitLab Flavored Markdown recognizes the URL and displays the source. +## Blockquotes -## Features extended from standard Markdown - -All standard Markdown formatting should work as expected in GitLab. Some standard -functionality is extended with additional features, without affecting the standard usage. -If a functionality is extended, the new option is listed as a sub-section. - -### Blockquotes +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#blockquotes). Use a blockquote to highlight information, such as a side note. It's generated by starting the lines of the blockquote with `>`: @@ -753,7 +783,7 @@ by starting the lines of the blockquote with `>`: Quote break. -> 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. +> 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 *use* **Markdown** in a blockquote. ``` > Blockquotes help you emulate reply text. @@ -761,14 +791,13 @@ Quote break. Quote break. -> 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. +> 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 *use* **Markdown** in a blockquote. -#### Multiline blockquote +### Multiline blockquote -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). -GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes -fenced by `>>>`, with a blank line before and after the block: +Create multi-line blockquotes fenced by `>>>`, with a blank line before and after the block: ```markdown @@ -794,11 +823,13 @@ trigger this problem. > > you can quote that without having to manually prepend `>` to every line! -### Code spans and blocks +## Code spans and blocks -You can highlight anything that should be viewed as code and not standard text. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#code-spans-and-blocks). -Inline code is highlighted with single backticks `` ` ``: +Highlight anything that should be viewed as code and not standard text. + +Inline code is formatted with single backticks `` ` ``: ```markdown Inline `code` has `back-ticks around` it. @@ -811,6 +842,9 @@ Inline `code` has `back-ticks around` it. To achieve a similar effect for a larger code example, you can: - Fence an entire block of code with triple backticks (```` ``` ````). + - You can use more than three backticks, as long as both the opening and closing set have the same number. + Use multiple backticks for example when you want to include [suggestions](project/merge_requests/reviews/suggestions.md#nest-code-blocks-in-suggestions) + in your code blocks, or the other way around. - Fence an entire block of code with triple tildes (`~~~`). - Indent it four or more spaces. @@ -852,10 +886,9 @@ is like using Tildes are OK too. ``` -#### Colored code and syntax highlighting +### Colored code and syntax highlighting -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). +[View this topic 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](https://github.com/rouge-ruby/rouge) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the @@ -917,44 +950,45 @@ s = "No highlighting is shown for this line." But let's throw in a <b>tag</b>. ``` -### Emphasis +## Emphasis + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emphasis). -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. +You can emphasize text in multiple ways. Use italics, bold, strikethrough, +or combine these emphasis styles together. Examples: ```markdown -Emphasis, aka italics, with *asterisks* or _underscores_. +Emphasis, or italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with double **asterisks** or __underscores__. +Strong emphasis, or bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. -Strikethrough uses two tildes. ~~Scratch this.~~ +Strikethrough with double tildes. ~~Scratch this.~~ ``` <!-- markdownlint-disable MD050 --> -Emphasis, aka italics, with *asterisks* or _underscores_. +Emphasis, or italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with double **asterisks** or __underscores__. +Strong emphasis, or bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. -Strikethrough uses two tildes. ~~Scratch this.~~ +Strikethrough with double tildes. ~~Scratch this.~~ <!-- markdownlint-enable MD050 --> -#### Multiple underscores in words and mid-word emphasis +### Multiple underscores in words and mid-word emphasis -If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). Avoid italicizing a portion of a word, especially when you're dealing with code and names that often appear with multiple underscores. -GitLab Flavored Markdown extends the standard Markdown standard by ignoring multiple underlines in words, + +GitLab Flavored Markdown ignores multiple underlines in words, to allow better rendering of Markdown documents discussing code: ```markdown @@ -989,9 +1023,11 @@ perform*complicated*task do*this*and*do*that*and*another thing -### Footnotes +## Footnotes + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#footnotes). -Footnotes add a link to a note that are rendered at the end of a Markdown file. +Footnotes add a link to a note 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. @@ -1026,7 +1062,9 @@ These are used to force the Vale ReferenceLinks check to skip these examples. [^footnote-42]: This text is another footnote. -### Headers +## Headings + +Create headings from 1 to 6 by using `#`. ```markdown # H1 @@ -1035,9 +1073,11 @@ These are used to force the Vale ReferenceLinks check to skip these examples. #### H4 ##### H5 ###### H6 +``` -Alternatively, for H1 and H2, an underline-ish style: +Alternatively, for H1 and H2, use an underline style: +```markdown Alt-H1 ====== @@ -1045,111 +1085,121 @@ Alt-H2 ------ ``` -#### Header IDs and links +### Heading IDs and links -GitLab Flavored Markdown extends the standard Markdown standard so that all Markdown-rendered headers automatically -get IDs, which can be linked to, except in comments. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#heading-ids-and-links). + +All Markdown-rendered headings automatically +get IDs that can be linked to, except in comments. On hover, a link to those IDs becomes visible to make it easier to copy the link to -the header to use it somewhere else. +the heading to use it somewhere else. -The IDs are generated from the content of the header according to the following rules: +The IDs are generated from the content of the heading according to the following rules: 1. All text is converted to lowercase. 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 +1. If a heading with the same ID has already been generated, a unique incrementing number is appended, starting at 1. Example: ```markdown -# This header has spaces in it -## This header has a :thumbsup: in it -# This header has Unicode in it: 한글 -## This header has spaces in it -### This header has spaces in it -## This header has 3.5 in it (and parentheses) +# This heading has spaces in it +## This heading has a :thumbsup: in it +# This heading has Unicode in it: 한글 +## This heading has spaces in it +### This heading has spaces in it +## This heading has 3.5 in it (and parentheses) ``` Would generate the following link IDs: -1. `this-header-has-spaces-in-it` -1. `this-header-has-a-in-it` -1. `this-header-has-unicode-in-it-한글` -1. `this-header-has-spaces-in-it-1` -1. `this-header-has-spaces-in-it-2` -1. `this-header-has-3-5-in-it-and-parentheses` +1. `this-heading-has-spaces-in-it` +1. `this-heading-has-a-in-it` +1. `this-heading-has-unicode-in-it-한글` +1. `this-heading-has-spaces-in-it-1` +1. `this-heading-has-spaces-in-it-2` +1. `this-heading-has-3-5-in-it-and-parentheses` -Emoji processing happens before the header IDs are generated. The +Emoji processing happens before the heading IDs are generated. The emoji is converted to an image, which is then removed from the ID. -### Horizontal Rule +## Horizontal rule + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#horizontal-rule). Create a horizontal rule by using three or more hyphens, asterisks, or underscores: ```markdown -Three or more hyphens, - --- -asterisks, - *** -or underscores - ___ ``` -### Images +--- -Examples: +--- + +--- + +## Images + +Embed images using inline or reference links. +To see title text, hover over the image. <!-- -The following codeblock uses HTML to skip the Vale ReferenceLinks test. -Do not change it back to a markdown codeblock. +The following examples use HTML to skip the Vale ReferenceLinks test. +Do not change it back to a markdown codeblocks. --> -<!-- markdownlint-disable proper-names --> +<!-- +DO NOT change the name of markdown_logo.png. This file is used for a test in +spec/controllers/help_controller_spec.rb. +--> -<pre class="highlight"><code>Inline-style (hover to see title text): +<!-- +The examples below use an in-line link to pass the Vale ReferenceLinks test. +Do not change to a reference style link. +--> - +Inline-style: -Reference-style (hover to see title text): +<!-- markdownlint-disable proper-names --> -![alt text1][logo] +<pre class="highlight"><code> + + -[logo]: img/markdown_logo.png "Title Text" </code></pre> -<!-- markdownlint-enable proper-names --> + -<!-- -DO NOT change the name of markdown_logo.png. This file is used for a test in -spec/controllers/help_controller_spec.rb. ---> +Reference-style: -Inline-style (hover to see title text): +<pre class="highlight"><code> - +![alt text1][logo] -Reference-style (hover to see title text): +[logo]: img/markdown_logo.png "Title Text" -<!-- -The example below uses an in-line link to pass the Vale ReferenceLinks test. -Do not change to a reference style link. ---> +</code></pre>  -#### Change the image or video dimensions +<!-- markdownlint-enable proper-names --> + +### Change the image or video dimensions > - Support for images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28118) in GitLab 15.7. > - Support for videos [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17139) in GitLab 15.9. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#change-the-image-or-video-dimensions). + You can control the width and height of an image or video by following the image with an attribute list. The value must an integer with a unit of either `px` (default) or `%`. @@ -1167,50 +1217,45 @@ For example You can also use the `img` HTML tag instead of Markdown and set its `height` and `width` parameters. -#### Videos +### Videos -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). Image tags that link to files with a video extension are automatically converted to a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: -```markdown -Here's a sample video: +Here's an example video: +```markdown  ``` -Here's a sample video: -  -#### Audio +### Audio -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). Similar to videos, link tags for files with an audio extension are automatically converted to an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`: -```markdown -Here's a sample audio clip: +Here's an example audio clip: +```markdown  ``` -Here's a sample audio clip: -  -### Inline HTML +## Inline HTML > Allowing `rel="license"` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20857) in GitLab 14.6. -To see the second example of Markdown rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). +[View this topic in GitLab](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 usually works pretty well. -See the documentation for HTML::Pipeline's [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) +See the documentation for `HTML::Pipeline`'s [SanitizationFilter](https://github.com/jch/html-pipeline/blob/v2.12.3/lib/html/pipeline/sanitization_filter.rb#L42) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` allowlist, GitLab allows `span`, `abbr`, `details` and `summary` elements. `rel="license"` is allowed on links to support the [Rel-License microformat](https://microformats.org/wiki/rel-license) and license attribution. @@ -1243,7 +1288,7 @@ are separated into their own lines: <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> - <dt>Markdown in HTML</dt> + <dt>Markdown in HTML with proper spacing</dt> <dd> Does *not* work **very** well. HTML tags work, in most cases. @@ -1261,7 +1306,7 @@ Markdown is fine in GitLab. <dt>Markdown in HTML</dt> <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd> - <dt>Markdown in HTML</dt> + <dt>Markdown in HTML with proper spacing</dt> <dd> Does <em>not</em> work <b>very</b> well. HTML tags work, in most cases. @@ -1269,38 +1314,33 @@ Markdown is fine in GitLab. </dd> </dl> -#### Collapsible section +### Collapsible section -To see the second Markdown example rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. For example, collapse a long log file so it takes up less screen space. ```html -<p> <details> -<summary>Click this to collapse/fold.</summary> +<summary>Click to expand</summary> These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> </details> -</p> ``` -<p> <details> -<summary>Click this to collapse/fold.</summary> +<summary>Click to expand</summary> These details <em>remain</em> <strong>hidden</strong> until expanded. <pre><code>PASTE LOGS HERE</code></pre> </details> -</p> --- @@ -1312,7 +1352,7 @@ Remember to leave a blank line before and after any Markdown sections, as shown <details> <summary> -Click this to _collapse/fold._ +Click to _expand._ </summary> @@ -1331,7 +1371,7 @@ works correctly in GitLab. --> <details> -<summary>Click this to <em>collapse/fold.</em></summary> +<summary>Click to <em>expand.</em></summary> These details <em>remain</em> <b>hidden</b> until expanded. @@ -1339,11 +1379,13 @@ These details <em>remain</em> <b>hidden</b> until expanded. </details> -### Line breaks +## Line breaks + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#line-breaks). A line break is inserted (a new paragraph starts) if the previous text is 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 +use one newline (press <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: @@ -1367,7 +1409,7 @@ These lines are only separated by single newlines, so they *do not break* and just follow the previous lines in the *same paragraph*. -#### Newlines +### Newlines GitLab Flavored Markdown adheres to the Markdown specification for handling [paragraphs and line breaks](https://spec.commonmark.org/current/). @@ -1382,7 +1424,7 @@ paragraph, with a blank line in between: ```markdown First paragraph. Another line in the same paragraph. -A third line in the same paragraph, but this time ending with two spaces.{space}{space} +A third line in the same paragraph, but this time ending with two spaces.<space><space> A new line directly under the first paragraph. Second paragraph. @@ -1390,7 +1432,9 @@ Another line, this time ending with a backslash.\ A new line due to the previous backslash. ``` -### Links +## Links + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#links). You can create links two ways: inline-style and reference-style. For example: @@ -1404,10 +1448,10 @@ Do not change it back to a markdown codeblock. - This line shows a [relative link to a file 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: +Using heading ID anchors: -- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-features-permissions) -- This line 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 heading ID](permissions.md#project-features-permissions) +- This line links to [a different section on the same page, using a "#" and the heading ID](#heading-ids-and-links) Using references: @@ -1427,10 +1471,10 @@ Some text to show that the reference links can follow later. - This line shows a [relative link to a file 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: +Using heading ID anchors: -- This line links to [a section on a different Markdown page, using a "#" and the header ID](permissions.md#project-members-permissions) -- This line 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 heading ID](permissions.md#project-members-permissions) +- This line links to [a different section on the same page, using a "#" and the heading ID](#heading-ids-and-links) Using references: @@ -1451,9 +1495,11 @@ 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. -#### URL auto-linking +### URL auto-linking + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#url-auto-linking). -GitLab Flavored Markdown auto-links almost any URL you put into your text: +Almost any URL you put into your text is auto-linked: ```markdown - https://www.google.com @@ -1469,12 +1515,15 @@ GitLab Flavored Markdown auto-links almost any URL you put into your text: - <https://www.google.com> - <https://www.google.com> - <ftp://ftp.us.debian.org/debian/> -- <smb://foo/bar/baz> -- <irc://irc.freenode.net/> +- <a href="smb://foo/bar/baz/">smb://foo/bar/baz</a> +- <a href="irc://irc.freenode.net">irc://irc.freenode.net</a> - <http://localhost:3000> <!-- vale gitlab.Spelling = YES --> -### Lists + +## Lists + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#lists). You can create ordered and unordered lists. @@ -1629,10 +1678,11 @@ For example: CommonMark ignores the blank line and renders this as one list with paragraph spacing. -### Superscripts / Subscripts +## Superscripts / Subscripts + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#superscripts-subscripts). -CommonMark and GitLab Flavored Markdown don't support the Redcarpet superscript syntax ( `x^2` ). -Use the standard HTML syntax for superscripts and subscripts: +For superscripts and subscripts, use the standard HTML syntax: ```html The formula for water is H<sub>2</sub>O @@ -1646,7 +1696,11 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. <!-- vale gitlab.Spelling = YES --> -### Keyboard HTML tag +GitLab Flavored Markdown doesn't support the Redcarpet superscript syntax ( `x^2` ). + +## Keyboard HTML tag + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#keyboard-html-tag). The `<kbd>` element is used to identify text that represents user keyboard input. Text surrounded by `<kbd>` tags is typically displayed in the browser's default monospace font. @@ -1656,27 +1710,27 @@ Press <kbd>Enter</kbd> to go to the next page. Press <kbd>Enter</kbd> to go to the next page. -### Tables +## Tables -Tables are not part of the core Markdown specification, but are part of GitLab Flavored Markdown. +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables-1). -#### Markdown +When creating tables: -1. The first line contains the headers, separated by "pipes" (`|`). -1. The second line separates the headers from the cells. - - The cells can contain only empty spaces, hyphens, and - (optionally) colons for horizontal alignment. - - Each cell must contain at least one hyphen, but adding more hyphens to a - cell does not change the cell's rendering. - - Any content other than hyphens, whitespace, or colons is not allowed -1. The third, and any following lines, contain the cell values. - - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, - but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. - - The cell sizes **don't** have to match each other. They are flexible, but must be separated - by pipes (`|`). - - You **can** have blank cells. -1. Column widths are calculated dynamically based on the content of the cells. -1. To use the pipe character (`|`) in the text and not as table delimiter, you must escape it with a backslash (`\|`). +- The first line contains the headers, separated by "pipes" (`|`). +- The second line separates the headers from the cells. + - The cells can contain only empty spaces, hyphens, and + (optionally) colons for horizontal alignment. + - Each cell must contain at least one hyphen, but adding more hyphens to a + cell does not change the cell's rendering. + - Any content other than hyphens, whitespace, or colons is not allowed +- The third, and any following lines, contain the cell values. + - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, + but they can be very long. You can also include HTML `<br>` tags to force newlines if needed. + - The cell sizes **don't** have to match each other. They are flexible, but must be separated + by pipes (`|`). + - You **can** have blank cells. +- Column widths are calculated dynamically based on the content of the cells. +- To use the pipe character (`|`) in the text and not as table delimiter, you must escape it with a backslash (`\|`). Example: @@ -1694,6 +1748,10 @@ Example: | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | +### Alignment + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#alignment). + Additionally, you can choose the alignment of text in columns by adding colons (`:`) to the sides of the "dash" lines in the second row. This affects every cell in the column: @@ -1712,6 +1770,10 @@ to the sides of the "dash" lines in the second row. This affects every cell in t [In GitLab itself](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables), the headers are always left-aligned in Chrome and Firefox, and centered in Safari. +### Cells with multiple lines + +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#cells-with-multiple-lines). + You can use HTML formatting to adjust the rendering of tables. For example, you can use `<br>` tags to force a cell to have multiple lines: @@ -1727,45 +1789,49 @@ use `<br>` tags to force a cell to have multiple lines: | 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, -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 -| header 1 | header 2 | -| --- | --- | -| cell 1 | cell 2 | -| cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | -``` - -To have fully functioning task lists in a table, create an HTML table with Markdown in the cells: - -```html -<table> -<thead> -<tr><th>header 1</th><th>header 2</th></tr> -</thead> -<tbody> -<tr> -<td>cell 1</td> -<td>cell 2</td> -</tr> -<tr> -<td>cell 3</td> -<td> +### Task lists in tables + +To add [task lists](#task-lists) with checkboxes, use HTML formatting. Using either: + +- **An HTML table with Markdown in the cells.** Tables formatted this way result in fully functioning + task lists. + + ```html + <table> + <thead> + <tr><th>header 1</th><th>header 2</th></tr> + </thead> + <tbody> + <tr> + <td>cell 1</td> + <td>cell 2</td> + </tr> + <tr> + <td>cell 3</td> + <td> + + - [ ] Task one + - [ ] Task two + + </td> + </tr> + </tbody> + </table> + ``` -- [ ] Task one -- [ ] Task two +- **A Markdown table with HTML list tags.** These tasks don't save their state when selected. + Tables formatted this way do not render properly on `docs.gitlab.com`. -</td> -</tr> -</tbody> -</table> -``` + ```markdown + | header 1 | header 2 | + | --- | --- | + | cell 1 | cell 2 | + | cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | + ``` -##### Copy and paste from a spreadsheet +You can also [create a table in the rich text editor](rich_text_editor.md#tables) and insert a task list then. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. +### Copy and paste from a spreadsheet If you're working in spreadsheet software (for example, Microsoft Excel, Google Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy and paste @@ -1779,7 +1845,7 @@ entry and paste the spreadsheet:  -#### JSON +### JSON > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86353) in GitLab 15.3. |