2020-05-26 23:08:26 -04:00
---
2020-07-29 08:09:45 -04:00
stage: Create
group: Source Code
2021-12-28 16:16:11 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-26 23:08:26 -04:00
---
2022-04-18 20:08:51 -04:00
# GitLab Flavored Markdown (GLFM) **(FREE)**
> The abbreviation [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/24592) from `GFM` to `GLFM` in GitLab 14.10.
2014-05-27 08:12:15 -04:00
2022-04-25 23:10:58 -04:00
When you enter text in the GitLab UI, GitLab assumes the text is in the Markdown language.
The text is rendered with a set of styles. These styles are called *GitLab Flavored Markdown* .
2019-06-26 20:28:39 -04:00
2021-12-01 13:15:19 -05:00
For example, in Markdown, an unordered list looks like this:
2018-06-14 04:30:16 -04:00
2021-05-24 14:10:28 -04:00
```markdown
- Cat
- Dog
- Turtle
```
When this list is rendered, it looks like this:
- Cat
- Dog
- Turtle
2016-03-10 13:54:13 -05:00
2021-05-24 14:10:28 -04:00
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.
2021-06-08 14:10:23 -04:00
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 ).
2021-05-24 14:10:28 -04:00
GitLab Flavored Markdown extends the [CommonMark specification ](https://spec.commonmark.org/current/ ).
2022-03-01 19:13:45 -05:00
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 ).
2013-06-27 17:58:43 -04:00
2021-05-24 14:10:28 -04:00
## Where you can use GitLab Flavored Markdown
2021-02-25 13:11:05 -05:00
You can use GitLab Flavored Markdown in the following areas:
2013-06-27 17:58:43 -04:00
2018-11-12 08:30:41 -05:00
- Comments
- Issues
- Merge requests
- Milestones
- Snippets (the snippet must be named with a `.md` extension)
- Wiki pages
- Markdown documents inside repositories
2021-05-24 14:10:28 -04:00
- Epics
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
You can also use other rich text files in GitLab. You might have to install a dependency
2021-05-24 14:10:28 -04:00
to do so. For more information, see the [`gitlab-markup` gem project ](https://gitlab.com/gitlab-org/gitlab-markup ).
2014-04-24 18:48:22 -04:00
2021-05-24 17:10:58 -04:00
### Differences between GitLab Flavored Markdown and standard Markdown
2018-09-06 04:23:42 -04:00
2021-05-24 17:10:58 -04:00
GitLab uses standard CommonMark formatting. However, GitLab Flavored Markdown
extends standard Markdown with features made specifically for GitLab.
2019-06-26 20:28:39 -04:00
2021-05-24 17:10:58 -04:00
Features not found in standard Markdown:
2019-06-26 20:28:39 -04:00
2021-05-26 14:10:52 -04:00
- [Color chips written in `HEX`, `RGB` or `HSL` ](#colors )
2019-11-20 07:06:01 -05:00
- [Diagrams and flowcharts ](#diagrams-and-flowcharts )
2021-05-24 17:10:58 -04:00
- [Emoji ](#emojis )
2019-06-26 20:28:39 -04:00
- [Front matter ](#front-matter )
- [Inline diffs ](#inline-diff )
- [Math equations and symbols written in LaTeX ](#math )
- [Task Lists ](#task-lists )
2020-02-06 01:08:52 -05:00
- [Table of Contents ](#table-of-contents )
2019-11-27 01:06:40 -05:00
- [Wiki specific Markdown ](#wiki-specific-markdown )
2019-06-26 20:28:39 -04:00
2021-05-24 17:10:58 -04:00
Features [extended from standard Markdown ](#features-extended-from-standard-markdown ):
2019-06-26 20:28:39 -04:00
2022-03-01 10:22:06 -05:00
| 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 ) |
2019-06-26 20:28:39 -04:00
2021-05-24 17:10:58 -04:00
## Features not found in standard Markdown
The following features are not found in standard Markdown.
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
### Colors
2013-06-27 17:58:43 -04:00
2021-06-08 14:10:23 -04:00
[View this topic in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors ).
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
You can write a color in the formats: `HEX` , `RGB` , or `HSL` .
2014-03-17 08:04:18 -04:00
2021-05-24 17:10:58 -04:00
- `HEX` : `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
- `RGB` : `` `RGB[A](R, G, B[, A])` ``
- `HSL` : `` `HSL[A](H, S, L[, A])` ``
2014-02-04 02:48:33 -05:00
2021-05-24 17:10:58 -04:00
Named colors are not supported.
2014-03-17 08:04:18 -04:00
2021-05-24 17:10:58 -04:00
Colors in backticks are followed by a color indicator:
2014-04-24 18:48:22 -04:00
2019-06-26 20:28:39 -04:00
```markdown
2020-02-28 22:07:51 -05:00
- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`
```
- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`
2013-06-27 17:58:43 -04:00
2019-11-20 07:06:01 -05:00
### Diagrams and flowcharts
2021-05-24 17:10:58 -04:00
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.
2019-11-20 07:06:01 -05:00
#### Mermaid
2016-07-24 04:23:40 -04:00
2021-01-28 16:09:04 -05:00
Visit the [official page ](https://mermaidjs.github.io/ ) for more details. The
[Mermaid Live Editor ](https://mermaid-js.github.io/mermaid-live-editor/ ) helps you
learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve
issues in your diagrams.
2016-07-24 04:23:40 -04:00
2021-01-28 16:09:04 -05:00
To generate a diagram or flowchart, write your text inside the `mermaid` block:
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
````markdown
2019-06-26 20:28:39 -04:00
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
2020-03-12 05:09:55 -04:00
````
2014-04-24 18:48:22 -04:00
2019-06-26 20:28:39 -04:00
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
2016-07-24 04:23:40 -04:00
2021-05-24 17:10:58 -04:00
You can also include subgraphs:
2019-07-30 16:34:50 -04:00
2020-03-12 05:09:55 -04:00
````markdown
2019-07-30 16:34:50 -04:00
```mermaid
graph TB
SubGraph1 --> SubGraph1Flow
subgraph "SubGraph 1 Flow"
SubGraph1Flow(SubNode 1)
SubGraph1Flow -- Choice1 --> DoChoice1
SubGraph1Flow -- Choice2 --> DoChoice2
end
subgraph "Main Graph"
Node1[Node 1] --> Node2[Node 2]
Node2 --> SubGraph1[Jump to SubGraph1]
SubGraph1 --> FinalThing[Final Thing]
end
```
2020-03-12 05:09:55 -04:00
````
2019-07-30 16:34:50 -04:00
```mermaid
graph TB
SubGraph1 --> SubGraph1Flow
subgraph "SubGraph 1 Flow"
SubGraph1Flow(SubNode 1)
SubGraph1Flow -- Choice1 --> DoChoice1
SubGraph1Flow -- Choice2 --> DoChoice2
end
subgraph "Main Graph"
Node1[Node 1] --> Node2[Node 2]
Node2 --> SubGraph1[Jump to SubGraph1]
SubGraph1 --> FinalThing[Final Thing]
end
```
2019-11-20 07:06:01 -05:00
#### PlantUML
2021-05-24 17:10:58 -04:00
To make PlantUML available in GitLab, a GitLab administrator must enable it. For more information, see the
[PlantUML & GitLab ](../administration/integration/plantuml.md ) page.
2019-11-20 07:06:01 -05:00
2020-11-28 16:09:37 -05:00
#### Kroki
2021-05-24 17:10:58 -04:00
To make Kroki available in GitLab, a GitLab administrator must enable it.
For more information, see the [Kroki integration ](../administration/integration/kroki.md ) page.
2020-11-28 16:09:37 -05:00
2021-05-24 17:10:58 -04:00
### Emojis
2015-05-25 16:22:46 -04:00
2021-06-08 14:10:23 -04:00
[View this topic in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis ).
2015-05-25 16:22:46 -04:00
2020-05-19 14:08:11 -04:00
```markdown
2019-06-26 20:28:39 -04:00
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
2013-06-27 17:58:43 -04:00
2021-02-25 13:11:05 -05:00
:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v:
2016-04-27 17:38:33 -04:00
2021-01-28 16:09:04 -05:00
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.
2016-07-24 04:23:40 -04:00
2021-10-28 11:09:42 -04:00
If you're new to this, don't be :fearful:. You can join the emoji :family:. Just look up one of the supported codes.
2016-04-27 17:38:33 -04:00
2019-06-26 20:28:39 -04:00
Consult the [Emoji Cheat Sheet ](https://www.emojicopy.com ) for a list of all supported emoji codes. :thumbsup:
2018-10-31 13:09:18 -04:00
```
2016-04-27 17:38:33 -04:00
2021-10-22 11:19:11 -04:00
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:
2016-04-27 17:38:33 -04:00
2021-10-22 11:19:11 -04:00
< 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" >
2016-04-27 17:38:33 -04:00
2021-10-22 11:19:11 -04:00
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.
2016-04-27 17:38:33 -04:00
2021-10-28 11:09:42 -04:00
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.
2016-04-27 17:38:33 -04:00
2021-10-22 11:19:11 -04:00
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" >
2016-04-27 17:38:33 -04:00
2021-05-24 17:10:58 -04:00
#### Emojis and your operating system
2020-10-12 05:08:38 -04:00
2021-05-24 17:10:58 -04:00
The previous emoji example uses hard-coded images. Rendered emojis
in GitLab may be different depending on the OS and browser used.
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
Most emojis are natively supported on macOS, Windows, iOS, Android, and fall back on image-based
emojis where there is no support.
2016-07-24 04:23:40 -04:00
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = NO -->
2021-10-22 02:10:16 -04:00
On Linux, you can download [Noto Color Emoji ](https://github.com/googlefonts/noto-emoji )
2020-04-07 23:09:31 -04:00
to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has
2019-06-26 20:28:39 -04:00
this font installed by default.
2016-01-25 16:36:44 -05:00
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = YES -->
2019-06-26 20:28:39 -04:00
### Front matter
2013-06-27 17:58:43 -04:00
2019-11-27 01:06:40 -05:00
Front matter is metadata included at the beginning of a Markdown document, preceding
2021-05-24 17:10:58 -04:00
the content. This data can be used by static site generators like [Jekyll ](https://jekyllrb.com/docs/front-matter/ ),
2019-06-26 20:28:39 -04:00
[Hugo ](https://gohugo.io/content-management/front-matter/ ), and many other applications.
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
When you view a Markdown file rendered by GitLab, front matter is displayed as-is,
2021-01-28 16:09:04 -05:00
in a box at the top of the document. The HTML content displays after the front matter. To view an example,
you can toggle between the source and rendered version of a
2021-11-29 19:12:59 -05:00
[GitLab documentation file ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/index.md ).
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
In GitLab, front matter is used only in Markdown files and wiki pages, not the other
2020-05-22 05:08:09 -04:00
places where Markdown formatting is supported. It must be at the very top of the document
2021-05-24 17:10:58 -04:00
and must be between delimiters.
2014-02-04 02:48:33 -05:00
2020-01-08 22:07:56 -05:00
The following delimiters are supported:
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
- YAML (`---`):
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
```yaml
2019-06-26 20:28:39 -04:00
---
title: About Front Matter
example:
2022-03-01 10:22:06 -05:00
language: yaml
2019-06-26 20:28:39 -04:00
---
2020-03-12 05:09:55 -04:00
```
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
- TOML (`+++`):
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
```toml
2019-06-26 20:28:39 -04:00
+++
title = "About Front Matter"
[example]
language = "toml"
+++
2020-03-12 05:09:55 -04:00
```
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
- JSON (`;;;`):
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
```json
2019-06-26 20:28:39 -04:00
;;;
{
"title": "About Front Matter"
"example": {
"language": "json"
}
}
;;;
2020-03-12 05:09:55 -04:00
```
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
Other languages are supported by adding a specifier to any of the existing
delimiters. For example:
```php
---php
$title = "About Front Matter";
$example = array(
'language' => "php",
);
---
2013-06-27 17:58:43 -04:00
```
2018-12-17 22:43:34 -05:00
### Inline diff
2016-05-18 12:05:51 -04:00
2021-06-08 14:10:23 -04:00
[View this topic in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff ).
2016-07-24 04:23:40 -04:00
2021-05-24 17:10:58 -04:00
With inline diff tags, you can display `{+ additions +}` or `[- deletions -]` .
2016-05-18 12:05:51 -04:00
2019-06-26 20:28:39 -04:00
The wrapping tags can be either curly braces or square brackets:
2016-05-18 12:05:51 -04:00
2019-06-26 20:28:39 -04:00
```markdown
- {+ addition 1 +}
- [+ addition 2 +]
- {- deletion 3 -}
- [- deletion 4 -]
2017-12-14 13:14:23 -05:00
```
2020-12-15 22:09:46 -05:00
![Inline diff as rendered by the GitLab interface ](img/inline_diff_01_v13_3.png )
2019-06-11 12:14:00 -04:00
2019-06-26 20:28:39 -04:00
---
2019-06-11 12:14:00 -04:00
2021-05-24 17:10:58 -04:00
However, you cannot mix the wrapping tags:
2016-05-18 12:05:51 -04:00
2019-06-26 20:28:39 -04:00
```markdown
- {+ addition +]
- [+ addition +}
- {- deletion -]
- [- deletion -}
2017-12-14 13:14:23 -05:00
```
2016-05-18 12:05:51 -04:00
2020-05-04 14:10:20 -04:00
If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` ` ` with a
2021-05-24 17:10:58 -04:00
backslash `\` . Otherwise the diff highlight does not render correctly:
2020-03-18 14:09:35 -04:00
```markdown
- {+ Just regular text +}
- {+ Text with `backticks` inside +}
- {+ Text with escaped \`backticks\` inside +}
```
2020-12-15 22:09:46 -05:00
![Inline diff with mixed formatting, as rendered by the GitLab interface ](img/inline_diff_02_v13_3.png )
2020-03-18 14:09:35 -04:00
2019-06-26 20:28:39 -04:00
### Math
2013-06-27 17:58:43 -04:00
2021-06-08 14:10:23 -04:00
[View this topic in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math ).
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
Math written in LaTeX syntax is rendered with [KaTeX ](https://github.com/KaTeX/KaTeX ).
2013-06-27 17:58:43 -04:00
2021-05-24 17:10:58 -04:00
Math written between dollar signs `$` is rendered inline with the text. Math written
in a [code block ](#code-spans-and-blocks ) with the language declared as `math` is rendered
2019-06-26 20:28:39 -04:00
on a separate line:
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
````markdown
2021-10-28 11:09:42 -04:00
This math is inline: $`a^2+b^2=c^2`$.
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
This math is on a separate line:
2018-08-16 10:21:50 -04:00
2019-06-26 20:28:39 -04:00
```math
a^2+b^2=c^2
2018-10-31 13:09:18 -04:00
```
2020-03-12 05:09:55 -04:00
````
2018-08-16 10:21:50 -04:00
2021-10-28 11:09:42 -04:00
This math is inline: $`a^2+b^2=c^2`$.
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
This math is on a separate line:
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
```math
a^2+b^2=c^2
```
2018-08-16 10:21:50 -04:00
2021-05-24 17:10:58 -04:00
_KaTeX only supports a [subset ](https://katex.org/docs/supported.html ) of LaTeX._
2018-08-16 10:21:50 -04:00
2021-05-24 17:10:58 -04:00
This syntax also works for the Asciidoctor `:stem: latexmath` . For details, see
2020-05-04 14:10:20 -04:00
the [Asciidoctor user manual ](https://asciidoctor.org/docs/user-manual/#activating-stem-support ).
2018-08-16 10:21:50 -04:00
2018-12-17 22:43:34 -05:00
### Task lists
2014-10-05 23:04:58 -04:00
2021-06-08 14:10:23 -04:00
[View this topic in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists ).
2016-07-24 04:23:40 -04:00
2021-05-26 14:10:52 -04:00
You can add task lists anywhere Markdown is supported.
2014-10-05 23:04:58 -04:00
2021-05-26 14:10:52 -04:00
- In issues, merge requests, and comments, you can click to select the boxes.
- In all other places, you cannot click to select the boxes. You must edit the Markdown manually
by adding or removing an `x` in the brackets.
To create a task list, follow the format of an ordered or unordered list:
2019-06-26 20:28:39 -04:00
```markdown
2015-05-06 18:55:57 -04:00
- [x] Completed task
- [ ] Incomplete task
2019-06-26 20:28:39 -04:00
- [ ] Sub-task 1
- [x] Sub-task 2
- [ ] Sub-task 3
2019-07-24 19:33:19 -04:00
2019-06-26 20:28:39 -04:00
1. [x] Completed task
1. [ ] Incomplete task
1. [ ] Sub-task 1
1. [x] Sub-task 2
2014-10-05 23:04:58 -04:00
```
2021-05-26 14:10:52 -04:00
![Task list as rendered by GitLab ](img/completed_tasks_v13_3.png )
2017-01-18 08:33:13 -05:00
2020-03-18 14:09:35 -04:00
### Table of contents
2020-02-06 01:08:52 -05:00
2021-05-26 14:10:52 -04:00
A table of contents is an unordered list that links to subheadings in the document.
2021-07-06 11:08:14 -04:00
You can add a table of contents to issues and merge requests, but you can't add one
2021-10-28 11:09:42 -04:00
to notes or comments. Add either the `[[_TOC_]]` or `[TOC]` tag on its own line
to the **Description** field of any of the supported content types:
- Markdown files.
- Wiki pages.
- Issues.
- Merge requests.
2021-07-06 11:08:14 -04:00
2020-02-06 01:08:52 -05:00
```markdown
2021-10-28 11:09:42 -04:00
This sentence introduces my wiki page.
2020-03-18 14:09:35 -04:00
2020-02-06 01:08:52 -05:00
[[_TOC_]]
2020-03-18 14:09:35 -04:00
## My first heading
First section content.
## My second heading
Second section content.
2020-02-06 01:08:52 -05:00
```
2021-01-28 16:09:04 -05:00
![Preview of an auto-generated table of contents in a Wiki ](img/markdown_toc_preview_v12_9.png )
2020-03-18 14:09:35 -04:00
2019-06-26 20:28:39 -04:00
### Wiki-specific Markdown
2017-01-18 08:33:13 -05:00
2021-05-26 14:10:52 -04:00
The following topics show how links inside wikis behave.
2014-10-05 23:04:58 -04:00
2020-03-18 14:09:35 -04:00
#### Wiki - direct page link
2016-07-12 13:28:39 -04:00
2021-05-26 14:10:52 -04:00
A direct page link includes the slug for a page that points to that page,
at the base level of the wiki.
2016-07-24 04:23:40 -04:00
2021-05-26 14:10:52 -04:00
This example links to a `documentation` page at the root of your wiki:
2016-07-12 13:28:39 -04:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to Documentation ](documentation )
```
2016-07-12 13:28:39 -04:00
2020-03-18 14:09:35 -04:00
#### Wiki - direct file link
2016-07-12 13:28:39 -04:00
2021-05-26 14:10:52 -04:00
A direct file link points to a file extension for a file, relative to the current page.
2016-07-12 13:28:39 -04:00
2021-05-26 14:10:52 -04:00
If the following example is on a page at `<your_wiki>/documentation/related` ,
it links to `<your_wiki>/documentation/file.md` :
2016-07-12 13:28:39 -04:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to File ](file.md )
```
2016-07-12 13:28:39 -04:00
2020-03-18 14:09:35 -04:00
#### Wiki - hierarchical link
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
A hierarchical link can be constructed relative to the current wiki page by using `./<page>` ,
2020-03-18 14:09:35 -04:00
`../<page>` , and so on.
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
If this example is on a page at `<your_wiki>/documentation/main` ,
it links to `<your_wiki>/documentation/related` :
2016-12-08 19:15:08 -05:00
2019-06-26 20:28:39 -04:00
```markdown
2020-11-08 22:09:03 -05:00
[Link to Related Page ](related )
2019-06-26 20:28:39 -04:00
```
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
If this example is on a page at `<your_wiki>/documentation/related/content` ,
it links to `<your_wiki>/documentation/main` :
2016-12-08 19:15:08 -05:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to Related Page ](../main )
```
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
If this example is on a page at `<your_wiki>/documentation/main` ,
it links to `<your_wiki>/documentation/related.md` :
2016-12-08 19:15:08 -05:00
2019-06-26 20:28:39 -04:00
```markdown
2020-11-08 22:09:03 -05:00
[Link to Related Page ](related.md )
2019-06-26 20:28:39 -04:00
```
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
If this example is on a page at `<your_wiki>/documentation/related/content` ,
it links to `<your_wiki>/documentation/main.md` :
2016-12-08 19:15:08 -05:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to Related Page ](../main.md )
```
2016-12-08 19:15:08 -05:00
2020-03-18 14:09:35 -04:00
#### Wiki - root link
2018-10-09 06:59:58 -04:00
2021-05-26 14:10:52 -04:00
A root link starts with a `/` and is relative to the wiki root.
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
This example links to `<wiki_root>/documentation` :
2016-12-08 19:15:08 -05:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to Related Page ](/documentation )
```
2016-12-08 19:15:08 -05:00
2021-05-26 14:10:52 -04:00
This example links to `<wiki_root>/miscellaneous.md` :
2017-12-20 06:39:40 -05:00
2019-06-26 20:28:39 -04:00
```markdown
[Link to Related Page ](/miscellaneous.md )
```
2017-12-20 06:39:40 -05:00
2021-05-24 17:10:58 -04:00
## GitLab-specific references
GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference
an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns
2021-08-09 02:10:01 -04:00
that reference into a link so you can navigate between them. All references to projects should use the
2021-07-06 11:08:14 -04:00
**project slug** rather than the project name.
2021-05-24 17:10:58 -04:00
Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand
version to reference other projects from the same namespace.
GitLab Flavored Markdown recognizes the following:
2022-03-01 10:22:06 -05:00
| references | input | cross-project reference | shortcut inside same namespace |
|:----------------------------------------------------------------------------|:------------------------------|:----------------------------------------|:-------------------------------|
| specific user | `@user_name` | | |
| specific group | `@group_name` | | |
| entire team | `@all` | | |
| 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` | |
2022-04-07 14:08:29 -04:00
| [iteration ](group/iterations/index.md ) | `*iteration:"iteration title"` | | |
2022-03-01 10:22:06 -05:00
| [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]` | | |
2021-05-24 17:10:58 -04:00
1. [Introduced ](https://gitlab.com/gitlab-org/gitlab/-/issues/222483 ) in GitLab 13.7.
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:
- 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]` .
2021-11-24 07:10:21 -05:00
### Show the issue, merge request, or epic title in the reference
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15694) in GitLab 14.6.
To include the title in the rendered link of an issue, 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)` .
2021-12-06 19:14:07 -05:00
URL references like `https://gitlab.com/gitlab-org/gitlab/-/issues/1234+` are also expanded.
2021-11-24 07:10:21 -05:00
2019-08-14 01:14:49 -04:00
### Embedding metrics in GitLab Flavored Markdown
2021-01-28 16:09:04 -05:00
Metric charts can be embedded in GitLab Flavored Markdown. Read
[Embedding Metrics in GitLab flavored Markdown ](../operations/metrics/embed.md ) for more details.
2019-08-14 01:14:49 -04:00
2021-05-24 17:10:58 -04:00
## Features extended from standard Markdown
2017-12-20 06:39:40 -05:00
2021-01-28 16:09:04 -05:00
All standard Markdown formatting should work as expected in GitLab. Some standard
2019-06-26 20:28:39 -04:00
functionality is extended with additional features, without affecting the standard usage.
2020-08-09 17:10:01 -04:00
If a functionality is extended, the new option is listed as a sub-section.
2017-12-20 06:39:40 -05:00
2019-06-26 20:28:39 -04:00
### Blockquotes
2017-12-20 06:39:40 -05:00
2021-01-28 16:09:04 -05:00
Use a blockquote to highlight information, such as a side note. It's generated
2019-06-26 20:28:39 -04:00
by starting the lines of the blockquote with `>` :
2017-12-20 06:39:40 -05:00
2019-06-26 20:28:39 -04:00
```markdown
2021-01-28 16:09:04 -05:00
> Blockquotes help you emulate reply text.
2019-06-26 20:28:39 -04:00
> This line is part of the same quote.
2017-12-20 06:39:40 -05:00
2019-06-26 20:28:39 -04:00
Quote break.
2017-12-20 06:39:40 -05:00
2021-10-28 11:09:42 -04:00
> 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.
2019-06-26 20:28:39 -04:00
```
2017-12-20 06:39:40 -05:00
2021-01-28 16:09:04 -05:00
> Blockquotes help you emulate reply text.
2019-06-26 20:28:39 -04:00
> This line is part of the same quote.
2017-12-20 06:39:40 -05:00
2019-06-26 20:28:39 -04:00
Quote break.
2017-11-21 22:12:04 -05:00
2021-10-28 11:09:42 -04:00
> 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.
2017-11-21 22:12:04 -05:00
2019-06-26 20:28:39 -04:00
#### Multiline blockquote
2017-11-21 22:12:04 -05:00
2021-06-08 14:10:23 -04:00
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 ).
2017-11-21 22:12:04 -05:00
2021-02-25 13:11:05 -05:00
GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes
2019-06-26 20:28:39 -04:00
fenced by `>>>` :
2017-11-21 22:12:04 -05:00
2020-02-28 22:07:51 -05:00
```markdown
2019-06-26 20:28:39 -04:00
>>>
If you paste a message from somewhere else
2017-11-21 22:12:04 -05:00
2019-06-26 20:28:39 -04:00
that spans multiple lines,
2017-11-21 22:12:04 -05:00
2019-06-26 20:28:39 -04:00
you can quote that without having to manually prepend `>` to every line!
>>>
2019-05-13 20:42:23 -04:00
```
2017-11-21 22:12:04 -05:00
2019-06-26 20:28:39 -04:00
>>>
If you paste a message from somewhere else
2017-11-21 22:12:04 -05:00
2019-06-26 20:28:39 -04:00
that spans multiple lines,
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
you can quote that without having to manually prepend `>` to every line!
>>>
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
### Code spans and blocks
2018-12-17 22:43:34 -05:00
2021-01-28 16:09:04 -05:00
You can highlight anything that should be viewed as code and not standard text.
2018-12-17 22:43:34 -05:00
2021-01-28 16:09:04 -05:00
Inline code is highlighted with single backticks `` ` ` `:
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
```markdown
Inline `code` has `back-ticks around` it.
```
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
Inline `code` has `back-ticks around` it.
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
---
2018-12-17 22:43:34 -05:00
2021-01-28 16:09:04 -05:00
To achieve a similar effect for a larger code example, you can:
- Fence an entire block of code with triple backticks (```` ``` ````).
- Fence an entire block of code with triple tildes (`~~~`).
- Indent it four or more spaces.
2018-12-17 22:43:34 -05:00
2020-03-12 05:09:55 -04:00
````markdown
```python
2019-06-26 20:28:39 -04:00
def function():
#indenting works just fine in the fenced code block
s = "Python code"
print s
```
2018-12-17 22:43:34 -05:00
2019-06-26 20:28:39 -04:00
Using 4 spaces
is like using
3-backtick fences.
2020-03-12 05:09:55 -04:00
````
2018-12-17 22:43:34 -05:00
2020-02-28 22:07:51 -05:00
```plaintext
2019-06-26 20:28:39 -04:00
~~~
Tildes are OK too.
~~~
2018-12-17 22:43:34 -05:00
```
2019-06-26 20:28:39 -04:00
The three examples above render as:
2013-06-27 17:58:43 -04:00
2020-02-28 22:07:51 -05:00
```python
2019-06-26 20:28:39 -04:00
def function():
#indenting works just fine in the fenced code block
s = "Python code"
print s
```
2013-06-27 17:58:43 -04:00
2020-02-28 22:07:51 -05:00
```plaintext
2019-07-14 23:02:30 -04:00
Using 4 spaces
is like using
3-backtick fences.
```
2013-06-27 17:58:43 -04:00
2020-03-12 05:09:55 -04:00
```plaintext
2019-06-26 20:28:39 -04:00
Tildes are OK too.
2020-03-12 05:09:55 -04:00
```
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
#### Colored code and syntax highlighting
2013-06-27 17:58:43 -04:00
2021-01-28 16:09:04 -05:00
If this section isn't rendered correctly,
2021-06-08 14:10:23 -04:00
[view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting ).
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
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
2019-10-09 20:06:44 -04:00
[Rouge project wiki ](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers ).
2021-01-28 16:09:04 -05:00
Syntax highlighting is supported only in code blocks, so you can't highlight inline code.
2014-02-04 02:48:33 -05:00
2021-01-28 16:09:04 -05:00
To fence and apply syntax highlighting to a block of code, append the code language
to the opening code declaration, three back-ticks (```` ``` ````) or three tildes (`~~~`):
2014-02-04 02:48:33 -05:00
2020-03-12 05:09:55 -04:00
````markdown
2019-06-26 20:28:39 -04:00
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
```python
def function():
#indenting works just fine in the fenced code block
s = "Python syntax highlighting"
print s
```
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
2014-02-04 02:48:33 -05:00
```
2019-06-26 20:28:39 -04:00
No language indicated, so no syntax highlighting.
2021-10-28 11:09:42 -04:00
s = "No highlighting is shown for this line."
2019-06-26 20:28:39 -04:00
But let's throw in a < b > tag< / b > .
2014-02-04 02:48:33 -05:00
```
2020-03-12 05:09:55 -04:00
````
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
The four examples above render as:
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
```python
def function():
#indenting works just fine in the fenced code block
s = "Python syntax highlighting"
print s
```
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
2020-02-28 22:07:51 -05:00
```plaintext
2019-06-26 20:28:39 -04:00
No language indicated, so no syntax highlighting.
2021-10-28 11:09:42 -04:00
s = "No highlighting is shown for this line."
2019-06-26 20:28:39 -04:00
But let's throw in a < b > tag< / b > .
```
2014-02-04 02:48:33 -05:00
2016-11-17 04:53:42 -05:00
### Emphasis
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
In Markdown, you can emphasize text in multiple ways. You can italicize, bold, strikethrough,
2021-01-28 16:09:04 -05:00
and combine these emphasis styles together.
2021-02-25 13:11:05 -05:00
Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown.
2019-06-26 20:28:39 -04:00
2018-06-07 16:09:50 -04:00
Examples:
2019-06-26 20:28:39 -04:00
```markdown
2013-06-27 17:58:43 -04:00
Emphasis, aka italics, with *asterisks* or _underscores_ .
2019-06-26 20:28:39 -04:00
Strong emphasis, aka bold, with double **asterisks** or __underscores__ .
2013-06-27 17:58:43 -04:00
2017-04-25 09:19:03 -04:00
Combined emphasis with **asterisks and _underscores_** .
2013-06-27 17:58:43 -04:00
Strikethrough uses two tildes. ~~Scratch this.~~
```
Emphasis, aka italics, with *asterisks* or _underscores_ .
2019-06-26 20:28:39 -04:00
Strong emphasis, aka bold, with double **asterisks** or __underscores__ .
2013-06-27 17:58:43 -04:00
Combined emphasis with **asterisks and _underscores_** .
Strikethrough uses two tildes. ~~Scratch this.~~
2019-06-26 20:28:39 -04:00
#### Multiple underscores in words and mid-word emphasis
2018-06-07 16:09:50 -04:00
2021-01-28 16:09:04 -05:00
If this section isn't rendered correctly,
2021-06-08 14:10:23 -04:00
[view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words ).
2014-02-04 02:48:33 -05:00
2021-01-28 16:09:04 -05:00
Avoid italicizing a portion of a word, especially when you're
dealing with code and names that often appear with multiple underscores.
2021-02-25 13:11:05 -05:00
GitLab Flavored Markdown extends the standard Markdown standard by ignoring multiple underlines in words,
2019-11-27 01:06:40 -05:00
to allow better rendering of Markdown documents discussing code:
2019-06-26 20:28:39 -04:00
2020-02-28 22:07:51 -05:00
```markdown
2019-06-26 20:28:39 -04:00
perform_complicated_task
do_this_and_do_that_and_another_thing
but_emphasis is_desired _here_
2013-06-27 17:58:43 -04:00
```
2019-06-26 20:28:39 -04:00
perform_complicated_task
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
do_this_and_do_that_and_another_thing
2018-06-07 16:09:50 -04:00
2019-06-26 20:28:39 -04:00
but_emphasis is_desired _here_
2014-02-04 02:48:33 -05:00
2019-06-26 20:28:39 -04:00
---
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
If you wish to emphasize only a part of a word, it can still be done with asterisks:
2015-06-26 18:37:22 -04:00
2020-05-19 14:08:11 -04:00
```markdown
2019-06-26 20:28:39 -04:00
perform*complicated*task
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
do*this*and*do*that*and*another thing
```
perform*complicated*task
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
do*this*and*do*that*and*another thing
### Footnotes
2018-06-07 16:09:50 -04:00
2020-08-09 17:10:01 -04:00
Footnotes add a link to a note that are rendered at the end of a Markdown file.
2020-01-14 19:09:05 -05:00
2020-03-18 14:09:35 -04:00
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
the note content.
2020-01-14 19:09:05 -05:00
2020-03-30 08:07:40 -04:00
Regardless of the tag names, the relative order of the reference tags determines the rendered
numbering.
2019-06-26 20:28:39 -04:00
2020-04-30 02:10:03 -04:00
<!--
2022-03-19 08:08:03 -04:00
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
Do not change it back to a markdown codeblock.
2020-04-30 02:10:03 -04:00
-->
< pre class = "highlight" > < code > A footnote reference tag looks like this: [^1]
2015-06-26 18:37:22 -04:00
2020-03-30 08:07:40 -04:00
This reference tag is a mix of letters and numbers. [^footnote-42]
2020-01-14 19:09:05 -05:00
2021-10-28 11:09:42 -04:00
[ ^1]: This text is inside a footnote.
2020-03-18 14:09:35 -04:00
2021-10-28 11:09:42 -04:00
[ ^footnote-42]: This text is another footnote.
2020-04-30 02:10:03 -04:00
< / code > < / pre >
2020-01-14 19:09:05 -05:00
2020-03-30 08:07:40 -04:00
A footnote reference tag looks like this:[^1]
2018-06-14 04:30:16 -04:00
2020-03-30 08:07:40 -04:00
This reference tag is a mix of letters and numbers.[^footnote-42]
2020-03-18 14:09:35 -04:00
2020-04-30 02:10:03 -04:00
<!--
Do not delete the single space before the [^1] and [^footnotes] references below.
These are used to force the Vale ReferenceLinks check to skip these examples.
-->
2021-10-28 11:09:42 -04:00
[^1]: This text is inside a footnote.
2020-03-18 14:09:35 -04:00
2021-10-28 11:09:42 -04:00
[^footnote-42]: This text is another footnote.
2019-06-26 20:28:39 -04:00
### Headers
```markdown
# H1
## H2
### H3
#### H4
##### H5
###### H6
Alternatively, for H1 and H2, an underline-ish style:
Alt-H1
======
Alt-H2
------
2015-06-26 18:37:22 -04:00
```
2019-06-26 20:28:39 -04:00
#### Header IDs and links
2018-06-07 16:09:50 -04:00
2021-02-25 13:11:05 -05:00
GitLab Flavored Markdown extends the standard Markdown standard so that all Markdown-rendered headers automatically
2019-06-26 20:28:39 -04:00
get IDs, which can be linked to, except in comments.
2015-06-26 18:37:22 -04:00
2019-06-26 20:28:39 -04:00
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.
2018-06-14 04:30:16 -04:00
2019-06-26 20:28:39 -04:00
The IDs are generated from the content of the header according to the following rules:
2015-06-26 18:37:22 -04:00
2019-06-26 20:28:39 -04:00
1. All text is converted to lowercase.
2020-03-18 14:09:35 -04:00
1. All non-word text (such as punctuation or HTML) is removed.
2019-06-26 20:28:39 -04:00
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
incrementing number is appended, starting at 1.
2015-06-26 18:37:22 -04:00
2018-06-07 16:09:50 -04:00
Example:
2020-02-28 22:07:51 -05:00
```markdown
2019-06-26 20:28:39 -04:00
# 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)
2015-06-26 18:37:22 -04:00
```
2019-06-26 20:28:39 -04:00
Would generate the following link IDs:
2015-06-26 18:37:22 -04:00
2019-06-26 20:28:39 -04:00
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`
2018-06-14 04:30:16 -04:00
2021-10-28 11:09:42 -04:00
Emoji processing happens before the header IDs are generated. The
emoji is converted to an image, which is then removed from the ID.
2015-06-26 18:37:22 -04:00
2019-06-26 20:28:39 -04:00
### Horizontal Rule
2013-06-27 17:58:43 -04:00
2021-01-28 16:09:04 -05:00
Create a horizontal rule by using three or more hyphens, asterisks, or underscores:
2013-06-27 17:58:43 -04:00
2019-04-09 06:56:36 -04:00
```markdown
2019-06-26 20:28:39 -04:00
Three or more hyphens,
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
---
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
asterisks,
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
***
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
or underscores
___
2019-04-09 06:56:36 -04:00
```
2013-06-27 17:58:43 -04:00
2016-11-17 04:53:42 -05:00
### Images
2013-06-27 17:58:43 -04:00
2018-06-07 16:09:50 -04:00
Examples:
2020-04-30 02:10:03 -04:00
<!--
2022-03-19 08:08:03 -04:00
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
Do not change it back to a markdown codeblock.
2020-04-30 02:10:03 -04:00
-->
< pre class = "highlight" > < code > Inline-style (hover to see title text):
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
![alt text ](img/markdown_logo.png "Title Text" )
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
Reference-style (hover to see title text):
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
![alt text1][logo]
2018-06-07 16:09:50 -04:00
2020-04-30 02:10:03 -04:00
[ logo]: img/markdown_logo.png "Title Text"
< / code > < / pre >
2013-06-27 17:58:43 -04:00
2020-02-03 10:08:45 -05:00
<!--
2021-10-28 11:09:42 -04:00
DO NOT change the name of markdown_logo.png. This file is used for a test in
2020-04-30 02:10:03 -04:00
spec/controllers/help_controller_spec.rb.
2020-02-03 10:08:45 -05:00
-->
2019-06-26 20:28:39 -04:00
Inline-style (hover to see title text):
2014-04-24 18:48:22 -04:00
2019-06-26 20:28:39 -04:00
![alt text ](img/markdown_logo.png "Title Text" )
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
Reference-style (hover to see title text):
2014-04-24 18:48:22 -04:00
2020-04-30 02:10:03 -04:00
<!--
The example below uses an in-line link to pass the Vale ReferenceLinks test.
Do not change to a reference style link.
-->
2013-06-27 17:58:43 -04:00
2020-04-30 02:10:03 -04:00
![alt text ](img/markdown_logo.png "Title Text" )
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
In the rare case where you must set a specific height or width for an image,
2021-09-20 11:12:39 -04:00
you can use the `img` HTML tag instead of Markdown and set its `height` and
`width` parameters.
2019-06-26 20:28:39 -04:00
#### Videos
2013-06-27 17:58:43 -04:00
2021-06-08 14:10:23 -04:00
If this section isn't rendered correctly, [view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos ).
2018-06-07 16:09:50 -04:00
2019-06-26 20:28:39 -04:00
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` :
2013-06-27 17:58:43 -04:00
2020-05-19 14:08:11 -04:00
```markdown
2019-06-26 20:28:39 -04:00
Here's a sample video:
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
![Sample Video ](img/markdown_video.mp4 )
2013-06-27 17:58:43 -04:00
```
2019-06-26 20:28:39 -04:00
Here's a sample video:
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
![Sample Video ](img/markdown_video.mp4 )
2013-06-27 17:58:43 -04:00
2019-10-09 08:06:13 -04:00
#### Audio
2021-06-08 14:10:23 -04:00
If this section isn't rendered correctly, [view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio ).
2019-10-09 08:06:13 -04:00
Similar to videos, link tags for files with an audio extension are automatically converted to
2019-12-01 16:06:52 -05:00
an audio player. The valid audio extensions are `.mp3` , `.oga` , `.ogg` , `.spx` , and `.wav` :
2019-10-09 08:06:13 -04:00
2020-05-19 14:08:11 -04:00
```markdown
2019-10-09 08:06:13 -04:00
Here's a sample audio clip:
![Sample Audio ](img/markdown_audio.mp3 )
```
Here's a sample audio clip:
![Sample Audio ](img/markdown_audio.mp3 )
2016-11-17 04:53:42 -05:00
### Inline HTML
2013-06-27 17:58:43 -04:00
2021-12-16 04:15:29 -05:00
> Allowing `rel="license"` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20857) in GitLab 14.6.
2021-01-28 16:09:04 -05:00
To see the second example of Markdown rendered in HTML,
2021-06-08 14:10:23 -04:00
[view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html ).
2013-06-27 17:58:43 -04:00
2020-08-09 17:10:01 -04:00
You can also use raw HTML in your Markdown, and it usually works pretty well.
2015-01-21 03:50:17 -05:00
2020-04-06 08:10:44 -04:00
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 )
2020-02-11 22:08:55 -05:00
class for the list of allowed HTML tags and attributes. In addition to the default
2020-06-03 11:08:05 -04:00
`SanitizationFilter` allowlist, GitLab allows `span` , `abbr` , `details` and `summary` elements.
2021-12-16 04:15:29 -05:00
`rel="license"` is allowed on links to support the [Rel-License microformat ](https://microformats.org/wiki/rel-license ) and license attribution.
2018-06-07 16:09:50 -04:00
2019-06-26 20:28:39 -04:00
```html
2013-06-27 17:58:43 -04:00
< dl >
< dt > Definition list< / dt >
< dd > Is something people use sometimes.< / dd >
< dt > Markdown in HTML< / dt >
2020-08-09 17:10:01 -04:00
< dd > Does *not* work **very** well. HTML < em > tags</ em > do < b > work</ b > , in most cases.</ dd >
2013-06-27 17:58:43 -04:00
< / dl >
```
< dl >
< dt > Definition list< / dt >
< dd > Is something people use sometimes.< / dd >
< dt > Markdown in HTML< / dt >
2020-08-09 17:10:01 -04:00
< dd > Does *not* work **very** well. HTML < em > tags</ em > do < b > work</ b > , in most cases.</ dd >
2019-06-26 20:28:39 -04:00
< / dl >
---
2020-03-18 14:09:35 -04:00
It's still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
2019-06-26 20:28:39 -04:00
are separated into their own lines:
```html
< dl >
< dt > Markdown in HTML< / dt >
2020-08-09 17:10:01 -04:00
< dd > Does *not* work **very** well. HTML tags work, in most cases.</ dd >
2019-06-26 20:28:39 -04:00
< dt > Markdown in HTML< / dt >
< dd >
2019-07-02 04:50:00 -04:00
2020-08-09 17:10:01 -04:00
Does *not* work **very** well. HTML tags work, in most cases.
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
< / dd >
< / dl >
```
2020-04-30 02:10:03 -04:00
<!--
2020-12-15 22:09:46 -05:00
The example below uses HTML to force correct rendering on docs.gitlab.com,
2020-08-09 17:10:01 -04:00
Markdown is fine in GitLab.
2020-04-30 02:10:03 -04:00
-->
2019-06-26 20:28:39 -04:00
< dl >
< dt > Markdown in HTML< / dt >
2020-08-09 17:10:01 -04:00
< dd > Does *not* work **very** well. HTML tags work, in most cases.</ dd >
2019-06-26 20:28:39 -04:00
< dt > Markdown in HTML< / dt >
< dd >
2019-07-02 04:50:00 -04:00
2020-08-09 17:10:01 -04:00
Does < em > not< / em > work < b > very< / b > well. HTML tags work, in most cases.
2019-07-02 04:50:00 -04:00
2019-06-26 20:28:39 -04:00
< / dd >
2013-06-27 17:58:43 -04:00
< / dl >
2021-05-10 14:10:41 -04:00
#### Collapsible section
2017-09-13 06:28:52 -04:00
2021-01-28 16:09:04 -05:00
To see the second Markdown example rendered in HTML,
2021-06-08 14:10:23 -04:00
[view it in GitLab ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary ).
2019-06-26 20:28:39 -04:00
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 )
2021-01-28 16:09:04 -05:00
tags. For example, collapse a long log file so it takes up less screen space.
2019-06-26 20:28:39 -04:00
```html
< p >
< details >
2020-03-18 14:09:35 -04:00
< summary > Click this to collapse/fold.< / summary >
2019-06-26 20:28:39 -04:00
2020-08-09 17:10:01 -04:00
These details < em > remain< / em > < strong > hidden< / strong > until expanded.
2019-06-26 20:28:39 -04:00
< pre > < code > PASTE LOGS HERE< / code > < / pre >
< / details >
< / p >
```
2017-09-13 06:28:52 -04:00
< p >
< details >
2020-03-18 14:09:35 -04:00
< summary > Click this to collapse/fold.< / summary >
2018-06-14 04:30:16 -04:00
2020-08-09 17:10:01 -04:00
These details < em > remain< / em > < strong > hidden< / strong > until expanded.
2017-09-13 06:28:52 -04:00
< pre > < code > PASTE LOGS HERE< / code > < / pre >
2018-06-14 04:30:16 -04:00
2017-09-13 06:28:52 -04:00
< / details >
< / p >
2019-06-26 20:28:39 -04:00
---
2021-01-28 16:09:04 -05:00
Markdown inside these tags is also supported.
2020-03-29 20:08:14 -04:00
2020-12-07 22:09:37 -05:00
NOTE:
2020-06-08 17:09:17 -04:00
If your Markdown isn't rendering correctly, try adding
`{::options parse_block_html="true" /}` to the top of the page, and add
`markdown="span"` to the opening summary tag like this: `<summary markdown="span">` .
2020-03-29 20:08:14 -04:00
Remember to leave a blank line after the `</summary>` tag and before the `</details>` tag,
as shown in the example:
2017-09-13 06:28:52 -04:00
2019-09-10 19:48:30 -04:00
````html
2017-09-13 06:28:52 -04:00
< details >
2020-03-18 14:09:35 -04:00
< summary > Click this to collapse/fold.< / summary >
2017-09-13 06:28:52 -04:00
2020-08-09 17:10:01 -04:00
These details _remain_ **hidden** until expanded.
2018-06-14 04:30:16 -04:00
2019-09-10 19:48:30 -04:00
```
2019-07-24 19:33:19 -04:00
PASTE LOGS HERE
2019-09-10 19:48:30 -04:00
```
2018-06-14 04:30:16 -04:00
2017-09-13 06:28:52 -04:00
< / details >
2019-09-10 19:48:30 -04:00
````
2017-09-13 06:28:52 -04:00
2020-04-30 02:10:03 -04:00
<!--
The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown
2020-08-09 17:10:01 -04:00
works correctly in GitLab.
2020-04-30 02:10:03 -04:00
-->
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
< details >
2020-03-18 14:09:35 -04:00
< summary > Click this to collapse/fold.< / summary >
2018-06-07 16:09:50 -04:00
2020-08-09 17:10:01 -04:00
These details < em > remain< / em > < b > hidden< / b > until expanded.
2013-06-27 17:58:43 -04:00
2019-09-10 19:48:30 -04:00
< pre > < code > PASTE LOGS HERE< / code > < / pre >
2019-06-26 20:28:39 -04:00
< / details >
2013-06-27 17:58:43 -04:00
2020-03-18 14:09:35 -04:00
### Line breaks
2013-06-27 17:58:43 -04:00
2020-08-09 17:10:01 -04:00
A line break is inserted (a new paragraph starts) if the previous text is
2021-10-28 11:09:42 -04:00
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
2021-01-28 16:09:04 -05:00
same paragraph. Use this approach if you want to keep long lines from wrapping, and keep
2020-06-26 08:08:51 -04:00
them editable:
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
```markdown
Here's a line for us to start with.
2013-06-27 17:58:43 -04:00
2020-08-09 17:10:01 -04:00
This longer line is separated from the one above by two newlines, so it is a *separate paragraph* .
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
This line is also a separate paragraph, but...
These lines are only separated by single newlines,
so they *do not break* and just follow the previous lines
in the *same paragraph* .
2013-06-27 17:58:43 -04:00
```
2019-06-26 20:28:39 -04:00
Here's a line for us to start with.
2013-06-27 17:58:43 -04:00
2020-08-09 17:10:01 -04:00
This longer line is separated from the one above by two newlines, so it is a *separate paragraph* .
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
This line is also a separate paragraph, but...
These lines are only separated by single newlines,
so they *do not break* and just follow the previous lines
in the *same paragraph* .
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
#### Newlines
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
GitLab Flavored Markdown adheres to the Markdown specification for handling
[paragraphs and line breaks ](https://spec.commonmark.org/current/ ).
2013-06-27 17:58:43 -04:00
2020-03-18 14:09:35 -04:00
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 ).
2013-06-27 17:58:43 -04:00
2021-01-28 16:09:04 -05:00
Need more control over line breaks or soft returns? Add a single line break
2020-08-09 17:10:01 -04:00
by ending a line with a backslash, or two or more spaces. Two newlines in a row create a new
2019-06-26 20:28:39 -04:00
paragraph, with a blank line in between:
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
```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 new line directly under the first paragraph.
Second paragraph.
Another line, this time ending with a backslash.\
A new line due to the previous backslash.
```
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
### Links
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
You can create links two ways: inline-style and reference-style. For example:
2017-04-25 09:19:03 -04:00
2020-04-30 02:10:03 -04:00
<!--
2022-03-19 08:08:03 -04:00
The following codeblock uses HTML to skip the Vale ReferenceLinks test.
Do not change it back to a markdown codeblock.
2020-04-30 02:10:03 -04:00
-->
2021-10-28 11:09:42 -04:00
< pre class = "highlight" >< code > - This line shows an [inline-style link ](https://www.google.com )
2022-03-19 08:08:03 -04:00
- This line shows a [link to a repository file in the same directory ](permissions.md )
- This line shows a [relative link to a file one directory higher ](../index.md )
2021-10-28 11:09:42 -04:00
- This line shows a [link that also has title text ](https://www.google.com "This link takes you to Google!" )
2015-02-11 17:50:31 -05:00
2019-06-26 20:28:39 -04:00
Using header ID anchors:
2013-06-27 17:58:43 -04:00
2022-03-19 08:08:03 -04:00
- This line links to [a section on a different Markdown page, using a "#" and the header ID ](permissions.md#project-features-permissions )
2021-10-28 11:09:42 -04:00
- This line links to [a different section on the same page, using a "#" and the header ID ](#header-ids-and-links )
2018-06-07 16:09:50 -04:00
2019-06-26 20:28:39 -04:00
Using references:
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
- This line shows a [reference-style link, see below][Arbitrary case-insensitive reference text]
2019-06-26 20:28:39 -04:00
- You can [use numbers for reference-style link definitions, see below][1]
- Or leave it empty and use the [link text itself][], see below.
2013-06-27 17:58:43 -04:00
2019-06-26 20:28:39 -04:00
Some text to show that the reference links can follow later.
2017-04-25 09:19:03 -04:00
2020-04-30 02:10:03 -04:00
[ arbitrary case-insensitive reference text]: https://www.mozilla.org/en-US/
[ 1]: https://slashdot.org
[ link text itself]: https://www.reddit.com
< / code > < / pre >
2013-06-27 17:58:43 -04:00
2021-10-28 11:09:42 -04:00
- This line shows an [inline-style link ](https://www.google.com )
2022-03-19 08:08:03 -04:00
- This line shows a [link to a repository file in the same directory ](permissions.md )
- This line shows a [relative link to a file one directory higher ](../index.md )
2021-10-28 11:09:42 -04:00
- This line shows a [link that also has title text ](https://www.google.com "This link takes you to Google!" )
2015-02-11 17:50:31 -05:00
2019-06-26 20:28:39 -04:00
Using header ID anchors:
2013-08-26 08:07:07 -04:00
2022-03-19 08:08:03 -04:00
- This line links to [a section on a different Markdown page, using a "#" and the header ID ](permissions.md#project-features-permissions )
2021-10-28 11:09:42 -04:00
- This line links to [a different section on the same page, using a "#" and the header ID ](#header-ids-and-links )
2013-08-26 08:07:07 -04:00
2019-06-26 20:28:39 -04:00
Using references:
2018-06-07 16:09:50 -04:00
2020-04-30 02:10:03 -04:00
<!--
The example below uses in-line links to pass the Vale ReferenceLinks test.
Do not change to reference style links.
-->
2013-08-26 08:07:07 -04:00
2021-10-28 11:09:42 -04:00
- This line is a [reference-style link, see below ](https://www.mozilla.org/en-US/ )
2020-04-30 02:10:03 -04:00
- You can [use numbers for reference-style link definitions, see below ](https://slashdot.org )
- Or leave it empty and use the [link text itself ](https://www.reddit.com ), see below.
2013-08-26 08:07:07 -04:00
2020-04-30 02:10:03 -04:00
Some text to show that the reference links can follow later.
2013-08-26 08:07:07 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2020-07-16 02:09:33 -04:00
Relative links do not allow the referencing of project files in a wiki
2021-10-28 11:09:42 -04:00
page, or a wiki page in a project file. The reason: a wiki is always
2019-06-26 20:28:39 -04:00
in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)`
2020-08-09 17:10:01 -04:00
points the link to `wikis/style` only when the link is inside of a wiki Markdown file.
2014-10-11 13:53:27 -04:00
2019-06-26 20:28:39 -04:00
#### URL auto-linking
2018-06-07 16:09:50 -04:00
2021-02-25 13:11:05 -05:00
GitLab Flavored Markdown auto-links almost any URL you put into your text:
2015-05-06 18:55:57 -04:00
2019-06-26 20:28:39 -04:00
```markdown
2019-06-30 23:36:23 -04:00
- https://www.google.com
2019-10-09 20:06:44 -04:00
- https://www.google.com
2019-06-30 23:36:23 -04:00
- ftp://ftp.us.debian.org/debian/
- smb://foo/bar/baz
2019-08-29 04:50:59 -04:00
- irc://irc.freenode.net/
2019-06-30 23:36:23 -04:00
- http://localhost:3000
2015-05-06 18:55:57 -04:00
```
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = NO -->
2019-07-02 04:50:00 -04:00
- < https: // www . google . com >
2019-10-09 20:06:44 -04:00
- < https: // www . google . com >
2019-07-02 04:50:00 -04:00
- < ftp: // ftp . us . debian . org / debian />
- < smb: // foo / bar / baz >
2019-08-29 04:50:59 -04:00
- < irc: // irc . freenode . net />
2019-07-02 04:50:00 -04:00
- < http: // localhost:3000 >
2018-06-07 16:09:50 -04:00
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = YES -->
2019-06-26 20:28:39 -04:00
### Lists
2015-05-06 18:55:57 -04:00
2021-10-28 11:09:42 -04:00
You can create ordered and unordered lists.
2019-09-10 19:48:30 -04:00
For an ordered list, add the number you want the list
2019-07-24 19:33:19 -04:00
to start with, like `1.` , followed by a space, at the start of each line for ordered lists.
2021-10-28 11:09:42 -04:00
After the first number, it does not matter what number you use. Ordered lists are
2019-07-24 19:33:19 -04:00
numbered automatically by vertical order, so repeating `1.` for all items in the
2020-08-09 17:10:01 -04:00
same list is common. If you start with a number other than `1.` , it uses that as the first
2021-10-28 11:09:42 -04:00
number, and counts up from there.
2016-04-15 05:14:22 -04:00
2019-06-26 20:28:39 -04:00
Examples:
2020-05-19 14:08:11 -04:00
```markdown
2019-06-26 20:28:39 -04:00
1. First ordered list item
2. Another item
2019-06-30 23:36:23 -04:00
- Unordered sub-list.
2019-06-26 20:28:39 -04:00
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. Next ordered sub-list item
4. And another item.
2016-04-15 05:14:22 -04:00
```
2016-08-02 06:34:49 -04:00
2020-04-30 02:10:03 -04:00
<!--
The "2." and "4." in the example above are changed to "1." below, to match the style
standards on docs.gitlab.com.
2021-03-10 04:09:29 -05:00
See https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#lists
2020-04-30 02:10:03 -04:00
-->
2019-07-18 22:20:32 -04:00
2019-06-26 20:28:39 -04:00
1. First ordered list item
2019-07-18 22:20:32 -04:00
1. Another item
2019-06-30 23:36:23 -04:00
- Unordered sub-list.
2019-06-26 20:28:39 -04:00
1. Actual numbers don't matter, just that it's a number
1. Ordered sub-list
1. Next ordered sub-list item
2019-07-18 22:20:32 -04:00
1. And another item.
2019-06-26 20:28:39 -04:00
2019-09-10 19:48:30 -04:00
For an unordered list, add a `-` , `*` or `+` , followed by a space, at the start of
each line for unordered lists, but you should not use a mix of them.
2020-05-19 14:08:11 -04:00
```markdown
2019-09-10 19:48:30 -04:00
Unordered lists can:
- use
- minuses
They can also:
* use
* asterisks
They can even:
+ use
+ pluses
```
2020-04-30 02:10:03 -04:00
<!--
The "*" and "+" in the example above are changed to "-" below, to match the style
standards on docs.gitlab.com.
2021-03-10 04:09:29 -05:00
See https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#lists
2020-04-30 02:10:03 -04:00
-->
2019-09-10 19:48:30 -04:00
Unordered lists can:
- use
- minuses
They can also:
- use
- asterisks
2019-07-24 19:33:19 -04:00
2019-09-10 19:48:30 -04:00
They can even:
2019-07-24 19:33:19 -04:00
2019-09-10 19:48:30 -04:00
- use
- pluses
2018-06-07 16:09:50 -04:00
2019-06-26 20:28:39 -04:00
---
2016-11-17 04:53:42 -05:00
2019-06-26 20:28:39 -04:00
If a list item contains multiple paragraphs, each subsequent paragraph should be indented
to the same level as the start of the list item text.
2018-06-14 04:30:16 -04:00
2019-06-26 20:28:39 -04:00
Example:
2018-06-14 04:30:16 -04:00
2019-06-26 20:28:39 -04:00
```markdown
1. First ordered list item
2018-06-14 04:30:16 -04:00
2019-06-26 20:28:39 -04:00
Second paragraph of first item.
2018-06-14 04:30:16 -04:00
2019-07-18 22:20:32 -04:00
1. Another item
2019-06-26 20:28:39 -04:00
```
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
1. First ordered list item
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
Second paragraph of first item.
2016-08-02 06:34:49 -04:00
2019-07-18 22:20:32 -04:00
1. Another item
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
---
2016-08-02 06:34:49 -04:00
2021-10-28 11:09:42 -04:00
If the first item's paragraph isn't indented with the proper number of spaces,
2020-08-09 17:10:01 -04:00
the paragraph appears outside the list, instead of properly indented under the list item.
2021-10-28 11:09:42 -04:00
For example:
2016-08-02 06:34:49 -04:00
2020-02-28 22:07:51 -05:00
```markdown
2019-06-26 20:28:39 -04:00
1. First ordered list item
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
Paragraph of first item.
2016-08-02 06:34:49 -04:00
2019-07-18 22:20:32 -04:00
1. Another item
2016-08-02 06:34:49 -04:00
```
2019-06-26 20:28:39 -04:00
1. First ordered list item
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
Paragraph of first item.
2016-08-02 06:34:49 -04:00
2019-07-18 22:20:32 -04:00
1. Another item
2019-06-26 20:28:39 -04:00
### Superscripts / Subscripts
2016-08-02 06:34:49 -04:00
2021-02-25 13:11:05 -05:00
CommonMark and GitLab Flavored Markdown don't support the Redcarpet superscript syntax ( `x^2` ).
2021-01-28 16:09:04 -05:00
Use the standard HTML syntax for superscripts and subscripts:
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
```html
The formula for water is H< sub > 2< / sub > O
while the equation for the theory of relativity is E = mc< sup > 2< / sup > .
```
2016-08-02 06:34:49 -04:00
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = NO -->
2019-06-26 20:28:39 -04:00
The formula for water is H< sub > 2< / sub > O
while the equation for the theory of relativity is E = mc< sup > 2< / sup > .
2016-08-02 06:34:49 -04:00
2021-01-22 16:09:10 -05:00
<!-- vale gitlab.Spelling = YES -->
2022-04-18 23:09:43 -04:00
### 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.
```html
Press < kbd > Enter< / kbd > to go to the next page.
```
Press < kbd > Enter< / kbd > to go to the next page.
2019-06-26 20:28:39 -04:00
### Tables
2016-08-02 06:34:49 -04:00
2021-02-25 13:11:05 -05:00
Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown.
2016-08-02 06:34:49 -04:00
2019-07-02 04:50:00 -04:00
1. The first line contains the headers, separated by "pipes" (`|`).
2021-05-25 11:10:33 -04:00
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
2019-06-26 20:28:39 -04:00
1. The third, and any following lines, contain the cell values.
2019-11-27 01:06:40 -05:00
- You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines,
2019-06-26 20:28:39 -04:00
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.
2021-05-25 11:10:33 -04:00
1. Column widths are calculated dynamically based on the content of the cells.
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
Example:
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
```markdown
| header 1 | header 2 | header 3 |
2021-05-25 11:10:33 -04:00
| --- | --- | --- |
2019-06-26 20:28:39 -04:00
| cell 1 | cell 2 | cell 3 |
2020-08-09 17:10:01 -04:00
| 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. |
2020-10-12 11:08:32 -04:00
| cell 7 | | cell 9 |
2019-06-26 20:28:39 -04:00
```
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
| header 1 | header 2 | header 3 |
2021-05-25 11:10:33 -04:00
| --- | --- | --- |
2019-06-26 20:28:39 -04:00
| cell 1 | cell 2 | cell 3 |
2020-09-17 11:09:24 -04:00
| 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. |
2020-10-12 11:08:32 -04:00
| cell 7 | | cell 9 |
2016-08-02 06:34:49 -04:00
2021-01-28 16:09:04 -05:00
Additionally, you can choose the alignment of text in columns by adding colons (`:`)
2020-10-12 11:08:32 -04:00
to the sides of the "dash" lines in the second row. This affects every cell in the column:
2016-08-02 06:34:49 -04:00
2019-06-26 20:28:39 -04:00
```markdown
2021-05-25 11:10:33 -04:00
| Left Aligned | Centered | Right Aligned |
| :--- | :---: | ---: |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
2019-06-26 20:28:39 -04:00
```
2016-08-02 06:34:49 -04:00
2021-05-25 11:10:33 -04:00
| Left Aligned | Centered | Right Aligned |
| :--- | :---: | ---: |
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
2016-11-17 04:53:42 -05:00
2021-06-08 14:10:23 -04:00
[In GitLab itself ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables ),
2020-10-12 11:08:32 -04:00
the headers are always left-aligned in Chrome and Firefox, and centered in Safari.
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:
```markdown
| Name | Details |
2021-05-25 11:10:33 -04:00
| --- | --- |
2021-10-28 11:09:42 -04:00
| Item1 | This text is on one line |
2020-10-12 11:08:32 -04:00
| Item2 | This item has:< br > - Multiple items< br > - That we want listed separately |
```
| Name | Details |
2021-05-25 11:10:33 -04:00
| --- | --- |
2021-10-28 11:09:42 -04:00
| Item1 | This text is on one line |
2020-10-12 11:08:32 -04:00
| Item2 | This item has:< br > - Multiple items< br > - That we want listed separately |
2021-01-28 16:09:04 -05:00
You can use HTML formatting in GitLab itself to add [task lists ](#task-lists ) with checkboxes,
2020-10-12 11:08:32 -04:00
but they do not render properly on `docs.gitlab.com` :
```markdown
| header 1 | header 2 |
2021-05-25 11:10:33 -04:00
| --- | --- |
2020-10-12 11:08:32 -04:00
| cell 1 | cell 2 |
| cell 3 | < ul > < li > - [ ] Task one < / li > < li > - [ ] Task two < / li > < / ul > |
```
2020-01-21 16:08:54 -05:00
#### Copy from spreadsheet and paste in Markdown
2022-03-01 10:22:06 -05:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7.
2020-01-21 16:08:54 -05:00
2020-03-18 14:09:35 -04:00
If you're working in spreadsheet software (for example, Microsoft Excel, Google
2021-01-28 16:09:04 -05:00
Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste
from a spreadsheet. For example, suppose you have the
2020-01-21 16:08:54 -05:00
following spreadsheet:
![Copy from spreadsheet ](img/markdown_copy_from_spreadsheet_v12_7.png )
Select the cells and copy them to your clipboard. Open a GitLab Markdown
entry and paste the spreadsheet:
![Paste to Markdown table ](img/markdown_paste_table_v12_7.png )
2013-06-27 17:58:43 -04:00
## References
2014-04-24 18:48:22 -04:00
- This document leveraged heavily from the [Markdown-Cheatsheet ](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet ).
2019-06-26 20:28:39 -04:00
- The original [Markdown Syntax Guide ](https://daringfireball.net/projects/markdown/syntax )
2019-11-27 01:06:40 -05:00
at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown.
2020-10-12 05:08:38 -04:00
- You can find the detailed specification for CommonMark in the [CommonMark Spec ](https://spec.commonmark.org/current/ ).
2021-01-28 16:09:04 -05:00
- The [CommonMark Dingus ](https://spec.commonmark.org/dingus/ ) helps you test CommonMark syntax.