markdown.md 48.9 KB
Newer Older
1
---
Marcia Ramos's avatar
Marcia Ramos committed
2 3
stage: Create
group: Source Code
4
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"
Marcia Ramos's avatar
Marcia Ramos committed
5
type: reference, howto
6 7
---

8
# GitLab Markdown
Marin Jankovski's avatar
Marin Jankovski committed
9

10
This Markdown guide is **valid only for the GitLab internal Markdown rendering system for entries and files**.
11
It is **not** valid for the [GitLab documentation website](https://docs.gitlab.com)
12
or the [GitLab main website](https://about.gitlab.com), as they both use
13
[Kramdown](https://kramdown.gettalong.org) as their Markdown engine. The documentation
14
website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown).
15
Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/markdown-guide/)
16 17
for a complete Kramdown reference.

18
NOTE:
19
We encourage you to view this document as [rendered by GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md).
20

Marcia Ramos's avatar
Marcia Ramos committed
21
## GitLab Flavored Markdown (GFM)
22

23
GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification](https://spec.commonmark.org/current/)
Amy Qualls's avatar
Amy Qualls committed
24
(which is based on standard Markdown) in several ways to add more features.
25
It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github/basic-writing-and-formatting-syntax).
26

27
You can use GFM in the following areas:
28

29 30 31 32 33 34 35
- Comments
- Issues
- Merge requests
- Milestones
- Snippets (the snippet must be named with a `.md` extension)
- Wiki pages
- Markdown documents inside repositories
36
- Epics **(ULTIMATE)**
37

38 39 40
You can also use other rich text files in GitLab. You might have to install a dependency
to do so. Please see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup)
for more information.
41

42
### Transition from Redcarpet to CommonMark
43

Amy Qualls's avatar
Amy Qualls committed
44 45 46 47 48 49 50 51 52 53 54
- In GitLab version 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet)
  was removed. All issues and comments, including those from pre-11.1, are now processed
  using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker).
- GitLab versions 11.3 and greater use CommonMark to process wiki pages and Markdown
  files (`*.md`) in repositories.
- GitLab versions 11.1 and greater use the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker)
  for Markdown processing of all new issues, merge requests, comments, and other Markdown
  content in the GitLab system.

The documentation website migrated its Markdown engine
[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108)
55 56 57
in October 2018.

You may have older issues, merge requests, or Markdown documents in your
Amy Qualls's avatar
Amy Qualls committed
58 59 60
repository that relied upon nuances of the GitLab RedCarpet version
of Markdown. Because CommonMark uses slightly stricter syntax, these documents
may now appear differently after the transition to CommonMark.
61

62
For example, numbered lists with nested lists may
63
render incorrectly:
64 65 66 67 68 69 70

```markdown
1. Chocolate
  - dark
  - milk
```

71 72
To correct their rendering, add a space to each nested item to align the `-` with the first
character of the top list item (`C` in this case):
73 74 75 76 77 78 79

```markdown
1. Chocolate
   - dark
   - milk
```

80 81 82 83
1. Chocolate
   - dark
   - milk

84
We flag any significant differences between Redcarpet and CommonMark Markdown in this document.
85

Amy Qualls's avatar
Amy Qualls committed
86
If you have many Markdown files, it can be tedious to determine
87
if they display correctly or not. You can use the
88
[`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark)
Amy Qualls's avatar
Amy Qualls committed
89 90 91 92 93
tool to generate a list of files and the
differences between how RedCarpet and CommonMark render the files. It indicates
if any changes are needed.

`diff_redcarpet_cmark` is not an officially supported product.
94

95
### GFM extends standard Markdown
96

Amy Qualls's avatar
Amy Qualls committed
97 98
GitLab makes full use of the standard (CommonMark) formatting, but also includes more
helpful features for GitLab users.
99

Evan Read's avatar
Evan Read committed
100
It makes use of [new Markdown features](#new-gfm-markdown-extensions),
101
not found in standard Markdown:
102

Amy Qualls's avatar
Amy Qualls committed
103
- [Color chips written in HEX, RGB or HSL](#colors)
104
- [Diagrams and flowcharts](#diagrams-and-flowcharts)
105 106 107 108 109 110
- [Emoji](#emoji)
- [Front matter](#front-matter)
- [Inline diffs](#inline-diff)
- [Math equations and symbols written in LaTeX](#math)
- [Special GitLab references](#special-gitlab-references)
- [Task Lists](#task-lists)
111
- [Table of Contents](#table-of-contents)
112
- [Wiki specific Markdown](#wiki-specific-markdown)
113

114 115
It also has [extended Markdown features](#standard-markdown-and-extensions-in-gitlab), without
changing how standard Markdown is used:
116

117
| Standard Markdown                     | Extended Markdown in GitLab |
118
| ------------------------------------- | ------------------------- |
119
| [blockquotes](#blockquotes)           | [multi-line blockquotes](#multiline-blockquote) |
120 121 122
| [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) |
123
| [images](#images)                     | [embedded videos](#videos) and [audio](#audio) |
124
| [line breaks](#line-breaks)           | [more line break control](#newlines) |
125 126
| [links](#links)                       | [automatically linking URLs](#url-auto-linking) |

127
## New GFM Markdown extensions
Evan Read's avatar
Evan Read committed
128

129
### Colors
130

Amy Qualls's avatar
Amy Qualls committed
131
If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors).
132

133
It's possible to have color written in HEX, RGB, or HSL format rendered with a color
134
indicator.
135

136
Supported formats (named colors are not supported):
137

138 139 140
- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
- RGB: `` `RGB[A](R, G, B[, A])` ``
- HSL: `` `HSL[A](H, S, L[, A])` ``
141

142
Color written inside backticks is followed by a color "chip":
143

144
```markdown
Mike Jang's avatar
Mike Jang committed
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
- `#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)`
165

166 167
### Diagrams and flowcharts

Marcel Amirault's avatar
Marcel Amirault committed
168
It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](https://plantuml.com).
169
It's also possible to use [Kroki](https://kroki.io) to create a wide variety of diagrams.
170 171

#### Mermaid
172

Evan Read's avatar
Evan Read committed
173
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3.
174

Amy Qualls's avatar
Amy Qualls committed
175 176 177 178
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.
179

Amy Qualls's avatar
Amy Qualls committed
180
To generate a diagram or flowchart, write your text inside the `mermaid` block:
181

182
````markdown
183 184 185 186 187 188 189
```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```
190
````
191

192 193 194 195 196 197 198
```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```
199

200 201
Subgraphs can also be included:

202
````markdown
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
```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
```
219
````
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237

```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
```

238 239 240 241
#### PlantUML

To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md).

242 243 244
#### Kroki

To make Kroki available in GitLab, a GitLab administrator needs to enable it first.
245
Read more in the [Kroki integration](../administration/integration/kroki.md) page.
246

247
### Emoji
248

Amy Qualls's avatar
Amy Qualls committed
249
If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji).
250

251
```markdown
252
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
253

254
:zap: You can use emoji anywhere GFM is supported. :v:
255

Amy Qualls's avatar
Amy Qualls committed
256
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.
257

258
If you're new to this, don't be :fearful:. You can join the emoji :family:. All you need to do is to look up one of the supported codes.
259

260
Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
Marcia Ramos's avatar
Marcia Ramos committed
261
```
262

263
Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> to your <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. Well we have a gift for you:
264

265
<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">
266

Amy Qualls's avatar
Amy Qualls committed
267
You can use it to point out a<img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> patches. If someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. People <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0;border: 0"> you for that.
268

269
If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. You can join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">. All you need to do is to look up one of the supported codes.
270

271
Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0;border: 0">
272

273 274
#### Emoji and your OS

Amy Qualls's avatar
Amy Qualls committed
275 276
The emoji example above uses hard-coded images for this documentation. Rendered emoji
in GitLab may appear different depending on the OS and browser used.
277

278 279
Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based
emoji where there is no support.
280

281 282
<!-- vale gitlab.Spelling = NO -->

283
On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/)
284
to get full native emoji support. Ubuntu 18.04 (like many modern Linux distributions) has
285
this font installed by default.
286

287 288
<!-- vale gitlab.Spelling = YES -->

289
### Front matter
290

291
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6.
292

293
Front matter is metadata included at the beginning of a Markdown document, preceding
294 295
its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/),
[Hugo](https://gohugo.io/content-management/front-matter/), and many other applications.
296

297
When you view a Markdown file rendered by GitLab, any front matter is displayed as-is,
Amy Qualls's avatar
Amy Qualls committed
298 299 300
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
[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md).
301

302
In GitLab, front matter is only used in Markdown files and wiki pages, not the other
303
places where Markdown formatting is supported. It must be at the very top of the document
304
and must be between delimiters, as explained below.
305

306
The following delimiters are supported:
307

308
- YAML (`---`):
309

310
  ```yaml
311 312 313 314 315
  ---
  title: About Front Matter
  example:
  language: yaml
  ---
316
  ```
317

318
- TOML (`+++`):
319

320
  ```toml
321 322 323 324 325
  +++
  title = "About Front Matter"
  [example]
  language = "toml"
  +++
326
  ```
327

328
- JSON (`;;;`):
329

330
  ```json
331 332 333 334 335 336 337 338
  ;;;
  {
    "title": "About Front Matter"
    "example": {
      "language": "json"
    }
  }
  ;;;
339
  ```
340

341 342 343 344 345 346 347 348 349 350
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",
);
---
351 352
```

353
### Inline diff
354

Amy Qualls's avatar
Amy Qualls committed
355
If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff).
356

357
With inline diff tags you can display `{+ additions +}` or `[- deletions -]`.
358

359
The wrapping tags can be either curly braces or square brackets:
360

361 362 363 364 365
```markdown
- {+ addition 1 +}
- [+ addition 2 +]
- {- deletion 3 -}
- [- deletion 4 -]
366 367
```

368
![Inline diff as rendered by the GitLab interface](img/inline_diff_01_v13_3.png)
369

370
---
371

372
However, the wrapping tags can't be mixed:
373

374 375 376 377 378
```markdown
- {+ addition +]
- [+ addition +}
- {- deletion -]
- [- deletion -}
379
```
380

381
If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a
382
backslash `\`, otherwise the diff highlight don't render correctly:
383 384 385 386 387 388 389

```markdown
- {+ Just regular text +}
- {+ Text with `backticks` inside +}
- {+ Text with escaped \`backticks\` inside +}
```

390
![Inline diff with mixed formatting, as rendered by the GitLab interface](img/inline_diff_02_v13_3.png)
391

392
### Math
393

394
If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math).
395

396
It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX).
397

398 399
Math written between dollar signs `$` are rendered inline with the text. Math written
inside a [code block](#code-spans-and-blocks) with the language declared as `math`, are rendered
400
on a separate line:
401

402
````markdown
403
This math is inline $`a^2+b^2=c^2`$.
404

405
This is on a separate line
406

407 408
```math
a^2+b^2=c^2
Marcia Ramos's avatar
Marcia Ramos committed
409
```
410
````
411

412
This math is inline $`a^2+b^2=c^2`$.
413

414
This is on a separate line
415

416 417 418
```math
a^2+b^2=c^2
```
419

420
_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._
421

422
This also works for the Asciidoctor `:stem: latexmath`. For details, see
423
the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support).
424

425
### Special GitLab references
426

427
GFM recognizes special GitLab related references. For example, you can reference
Amy Qualls's avatar
Amy Qualls committed
428
an issue, a commit, a team member, or even an entire project team. GFM turns
429
that reference into a link so you can navigate between them.
430

431
Additionally, GFM recognizes certain cross-project references and also has a shorthand
432
version to reference other projects from the same namespace.
433

434
GFM recognizes the following:
435

Amy Qualls's avatar
Amy Qualls committed
436
| references                      | input                      | cross-project reference                 | shortcut inside same namespace |
437 438 439 440 441 442 443 444
| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- |
| 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`                  |
445
| epic **(ULTIMATE)**             | `&123`                     | `group1/subgroup&123`                   |                                |
446
| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]`      | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]`  |
447 448 449
| 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"`    |
450
| scoped label by name            | `~"priority::high"`        | `namespace/project~"priority::high"`    | `project~"priority::high"`     |
451 452 453 454 455
| 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`  |
456 457
| repository file references      | `[README](doc/README.md)`  |                                         |                                |
| repository file line references | `[README](doc/README.md#L13)` |                                      |                                |
458 459
| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123`    | `project^alert#123`            |

460 461
1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7.

Amy Qualls's avatar
Amy Qualls committed
462 463
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
464
recognized and formatted with text `#123`.
465

466 467
In addition to this, links to some objects are also recognized and formatted. Some examples of these are:

468
- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)`
469 470
- 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]`.
471

472
### Task lists
Vinnie Okada's avatar
Vinnie Okada committed
473

Amy Qualls's avatar
Amy Qualls committed
474
If this section isn't rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists).
475

Amy Qualls's avatar
Amy Qualls committed
476 477 478 479
You can add task lists anywhere Markdown is supported, but only issues, merge requests, and
comments support clicking to toggle the boxes. In other
places, you must edit the Markdown manually to change the status by adding or
removing an `x` inside the square brackets.
Vinnie Okada's avatar
Vinnie Okada committed
480

481 482 483 484
To create a task list, add a specially-formatted Markdown list. You can use either
unordered or ordered lists:

```markdown
485 486
- [x] Completed task
- [ ] Incomplete task
487 488 489
  - [ ] Sub-task 1
  - [x] Sub-task 2
  - [ ] Sub-task 3
490

491 492 493 494
1. [x] Completed task
1. [ ] Incomplete task
   1. [ ] Sub-task 1
   1. [x] Sub-task 2
Vinnie Okada's avatar
Vinnie Okada committed
495 496
```

Amy Qualls's avatar
Amy Qualls committed
497
![Task list as rendered by the GitLab interface](img/completed_tasks_v13_3.png)
498

499
### Table of contents
500

Amy Qualls's avatar
Amy Qualls committed
501 502 503
Add a table of contents to a Markdown file, wiki page, issue request, or merge request
description by adding the tag `[[_TOC_]]` on its own line.
It displays an unordered list that links to subheadings in the document.
504 505

```markdown
506 507
This is an intro sentence to my Wiki page.

508
[[_TOC_]]
509 510 511 512 513 514 515 516

## My first heading

First section content.

## My second heading

Second section content.
517 518
```

Amy Qualls's avatar
Amy Qualls committed
519
![Preview of an auto-generated table of contents in a Wiki](img/markdown_toc_preview_v12_9.png)
520

521
### Wiki-specific Markdown
522

523
The following examples show how links inside wikis behave.
Vinnie Okada's avatar
Vinnie Okada committed
524

525
#### Wiki - direct page link
526

527
A link which just includes the slug for a page points to that page,
528
_at the base level of the wiki_.
529

530
This snippet would link to a `documentation` page at the root of your wiki:
531

532 533 534
```markdown
[Link to Documentation](documentation)
```
535

536
#### Wiki - direct file link
537

538
Links with a file extension point to that file, _relative to the current page_.
539

540 541
If the snippet below was placed on a page at `<your_wiki>/documentation/related`,
it would link to `<your_wiki>/documentation/file.md`:
542

543 544 545
```markdown
[Link to File](file.md)
```
546

547
#### Wiki - hierarchical link
548

549
A link can be constructed relative to the current wiki page using `./<page>`,
550
`../<page>`, and so on.
551

552 553
If this snippet was placed on a page at `<your_wiki>/documentation/main`,
it would link to `<your_wiki>/documentation/related`:
554

555
```markdown
556
[Link to Related Page](related)
557
```
558

559 560
If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
it would link to `<your_wiki>/documentation/main`:
561

562 563 564
```markdown
[Link to Related Page](../main)
```
565

566 567
If this snippet was placed on a page at `<your_wiki>/documentation/main`,
it would link to `<your_wiki>/documentation/related.md`:
568

569
```markdown
570
[Link to Related Page](related.md)
571
```
572

573 574
If this snippet was placed on a page at `<your_wiki>/documentation/related/content`,
it would link to `<your_wiki>/documentation/main.md`:
575

576 577 578
```markdown
[Link to Related Page](../main.md)
```
579

580
#### Wiki - root link
581

582
A link starting with a `/` is relative to the wiki root.
583

584
This snippet links to `<wiki_root>/documentation`:
585

586 587 588
```markdown
[Link to Related Page](/documentation)
```
589

590
This snippet links to `<wiki_root>/miscellaneous.md`:
591

592 593 594
```markdown
[Link to Related Page](/miscellaneous.md)
```
595

596 597
### Embedding metrics in GitLab Flavored Markdown

Amy Qualls's avatar
Amy Qualls committed
598 599
Metric charts can be embedded in GitLab Flavored Markdown. Read
[Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details.
600

601
## Standard Markdown and extensions in GitLab
602

Amy Qualls's avatar
Amy Qualls committed
603
All standard Markdown formatting should work as expected in GitLab. Some standard
604
functionality is extended with additional features, without affecting the standard usage.
605
If a functionality is extended, the new option is listed as a sub-section.
606

607
### Blockquotes
608

Amy Qualls's avatar
Amy Qualls committed
609
Use a blockquote to highlight information, such as a side note. It's generated
610
by starting the lines of the blockquote with `>`:
611

612
```markdown
Amy Qualls's avatar
Amy Qualls committed
613
> Blockquotes help you emulate reply text.
614
> This line is part of the same quote.
615

616
Quote break.
617

Amy Qualls's avatar
Amy Qualls committed
618
> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
619
```
620

Amy Qualls's avatar
Amy Qualls committed
621
> Blockquotes help you emulate reply text.
622
> This line is part of the same quote.
623

624
Quote break.
625

Amy Qualls's avatar
Amy Qualls committed
626
> This is a very long line that is still quoted properly when it wraps. Keep writing to make sure this line is long enough to actually wrap for everyone. You can also *add* **Markdown** into a blockquote.
627

628
#### Multiline blockquote
629

Amy Qualls's avatar
Amy Qualls committed
630
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).
631

632
GFM extends the standard Markdown by also supporting multi-line blockquotes
633
fenced by `>>>`:
634

635
```markdown
636 637
>>>
If you paste a message from somewhere else
638

639
that spans multiple lines,
640

641 642
you can quote that without having to manually prepend `>` to every line!
>>>
643
```
644

645 646
>>>
If you paste a message from somewhere else
647

648
that spans multiple lines,
649

650 651
you can quote that without having to manually prepend `>` to every line!
>>>
652

653
### Code spans and blocks
654

Amy Qualls's avatar
Amy Qualls committed
655
You can highlight anything that should be viewed as code and not standard text.
656

Amy Qualls's avatar
Amy Qualls committed
657
Inline code is highlighted with single backticks `` ` ``:
658

659 660 661
```markdown
Inline `code` has `back-ticks around` it.
```
662

663
Inline `code` has `back-ticks around` it.
664

665
---
666

Amy Qualls's avatar
Amy Qualls committed
667 668 669 670 671
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.
672

673 674
````markdown
```python
675 676 677 678 679
def function():
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s
```
680

681 682 683
    Using 4 spaces
    is like using
    3-backtick fences.
684
````
685

686
```plaintext
687 688 689
~~~
Tildes are OK too.
~~~
690 691
```

692
The three examples above render as:
693

694
```python
695 696 697 698 699
def function():
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s
```
700

701
```plaintext
702 703 704 705
Using 4 spaces
is like using
3-backtick fences.
```
706

707
```plaintext
708
Tildes are OK too.
709
```
710

711
#### Colored code and syntax highlighting
712

Amy Qualls's avatar
Amy Qualls committed
713 714
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).
715

716 717
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
718
[Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
Amy Qualls's avatar
Amy Qualls committed
719
Syntax highlighting is supported only in code blocks, so you can't highlight inline code.
720

Amy Qualls's avatar
Amy Qualls committed
721 722
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 (`~~~`):
723

724
````markdown
725 726 727 728
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
729

730 731 732 733 734 735
```python
def function():
    #indenting works just fine in the fenced code block
    s = "Python syntax highlighting"
    print s
```
736

737 738 739 740 741
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
742 743

```
744 745 746
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
747
```
748
````
749

750
The four examples above render as:
751

752 753 754 755
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
756

757 758 759 760 761 762 763 764 765 766 767 768 769
```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
```

770
```plaintext
771 772 773 774
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
```
775

776
### Emphasis
777

778
There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough,
Amy Qualls's avatar
Amy Qualls committed
779
and combine these emphasis styles together.
780
Strikethrough is not part of the core Markdown standard, but is part of GFM.
781

782 783
Examples:

784
```markdown
785 786
Emphasis, aka italics, with *asterisks* or _underscores_.

787
Strong emphasis, aka bold, with double **asterisks** or __underscores__.
788

Simon Hardt's avatar
Simon Hardt committed
789
Combined emphasis with **asterisks and _underscores_**.
790 791 792 793 794 795

Strikethrough uses two tildes. ~~Scratch this.~~
```

Emphasis, aka italics, with *asterisks* or _underscores_.

796
Strong emphasis, aka bold, with double **asterisks** or __underscores__.
797 798 799 800 801

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

802
#### Multiple underscores in words and mid-word emphasis
803

Amy Qualls's avatar
Amy Qualls committed
804 805
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).
806

Amy Qualls's avatar
Amy Qualls committed
807 808
Avoid italicizing a portion of a word, especially when you're
dealing with code and names that often appear with multiple underscores.
809 810
GFM extends the standard Markdown standard by ignoring multiple underlines in words,
to allow better rendering of Markdown documents discussing code:
811

812
```markdown
813 814 815 816 817
perform_complicated_task

do_this_and_do_that_and_another_thing

but_emphasis is_desired _here_
818 819
```

820
perform_complicated_task
Evan Read's avatar
Evan Read committed
821

822
do_this_and_do_that_and_another_thing
823

824
but_emphasis is_desired _here_
825

826
---
827

828
If you wish to emphasize only a part of a word, it can still be done with asterisks:
829

830
```markdown
831
perform*complicated*task
Evan Read's avatar
Evan Read committed
832

833 834 835 836
do*this*and*do*that*and*another thing
```

perform*complicated*task
Evan Read's avatar
Evan Read committed
837

838 839 840
do*this*and*do*that*and*another thing

### Footnotes
841

842
Footnotes add a link to a note that are rendered at the end of a Markdown file.
843

844 845
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
the note content.
846

847 848
Regardless of the tag names, the relative order of the reference tags determines the rendered
numbering.
849

850
Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore
851
(`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/24423) is
852
resolved.
853

854 855 856 857 858
<!--
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
-->

<pre class="highlight"><code>A footnote reference tag looks like this: [^1]
859

860
This reference tag is a mix of letters and numbers. [^footnote-42]
861

862
&#91;^1]: This is the text inside a footnote.
863

864 865
&#91;^footnote-42]: This is another footnote.
</code></pre>
866

867
A footnote reference tag looks like this:[^1]
868

869
This reference tag is a mix of letters and numbers.[^footnote-42]
870

871 872 873 874 875 876
<!--
Do not delete the single space before the [^1] and [^footnotes] references below.
These are used to force the Vale ReferenceLinks check to skip these examples.
-->

 [^1]: This is the text inside a footnote.
877

878
 [^footnote-42]: This is another footnote.
879

880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896
### Headers

```markdown
# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------
897 898
```

899
#### Header IDs and links
900

901
GFM extends the standard Markdown standard so that all Markdown-rendered headers automatically
902
get IDs, which can be linked to, except in comments.
903

904 905
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.
906

907
The IDs are generated from the content of the header according to the following rules:
908

909
1. All text is converted to lowercase.
910
1. All non-word text (such as punctuation or HTML) is removed.
911 912 913 914
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.
915

916 917
Example:

918
```markdown
919 920 921 922 923 924
# 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)
925 926
```

927
Would generate the following link IDs:
928

929 930 931 932 933 934
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`
935

936 937
Note that the emoji processing happens before the header IDs are generated, so the
emoji is converted to an image which is then removed from the ID.
938

939
### Horizontal Rule
940

Amy Qualls's avatar
Amy Qualls committed
941
Create a horizontal rule by using three or more hyphens, asterisks, or underscores:
942

943
```markdown
944
Three or more hyphens,
945

946
---
947

948
asterisks,
949

950
***
951

952 953 954
or underscores

___
955
```
956

957
### Images
958

959 960
Examples:

961 962 963 964 965
<!--
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
-->

<pre class="highlight"><code>Inline-style (hover to see title text):
966

967
![alt text](img/markdown_logo.png "Title Text")
968

969
Reference-style (hover to see title text):
970

971
![alt text1][logo]
972

973 974
&#91;logo]: img/markdown_logo.png "Title Text"
</code></pre>
975

976
<!--
977 978
DO NOT change the name of markdown_logo.png. This is used for a test in
spec/controllers/help_controller_spec.rb.
979 980
-->

981
Inline-style (hover to see title text):
982

983
![alt text](img/markdown_logo.png "Title Text")
984

985
Reference-style (hover to see title text):
986

987 988 989 990
<!--
The example below uses an in-line link to pass the Vale ReferenceLinks test.
Do not change to a reference style link.
-->
991

992
![alt text](img/markdown_logo.png "Title Text")
993

994
#### Videos
995

Amy Qualls's avatar
Amy Qualls committed
996
If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos).
997

998 999
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`:
1000

1001
```markdown
1002
Here's a sample video:
1003

1004
![Sample Video](img/markdown_video.mp4)
1005 1006
```

1007
Here's a sample video:
1008

1009
![Sample Video](img/markdown_video.mp4)
1010

1011 1012
#### Audio

Amy Qualls's avatar
Amy Qualls committed
1013
If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio).
1014 1015

Similar to videos, link tags for files with an audio extension are automatically converted to
1016
an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`:
1017

1018
```markdown
1019 1020 1021 1022 1023 1024 1025 1026 1027
Here's a sample audio clip:

![Sample Audio](img/markdown_audio.mp3)
```

Here's a sample audio clip:

![Sample Audio](img/markdown_audio.mp3)

1028
### Inline HTML
1029

Amy Qualls's avatar
Amy Qualls committed
1030 1031
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).
1032

1033
You can also use raw HTML in your Markdown, and it usually works pretty well.
1034

1035
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)
1036
class for the list of allowed HTML tags and attributes. In addition to the default
1037
`SanitizationFilter` allowlist, GitLab allows `span`, `abbr`, `details` and `summary` elements.
1038

1039
```html
1040 1041 1042 1043 1044
<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
1045
  <dd>Does *not* work **very** well. HTML <em>tags</em> do <b>work</b>, in most cases.</dd>
1046 1047 1048 1049 1050 1051 1052 1053
</dl>
```

<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
1054
  <dd>Does *not* work **very** well. HTML <em>tags</em> do <b>work</b>, in most cases.</dd>
1055 1056 1057 1058
</dl>

---

1059
It's still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
1060 1061 1062 1063 1064
are separated into their own lines:

```html
<dl>
  <dt>Markdown in HTML</dt>
1065
  <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd>
1066 1067 1068

  <dt>Markdown in HTML</dt>
  <dd>
Evan Read's avatar
Evan Read committed
1069

1070
  Does *not* work **very** well. HTML tags work, in most cases.
Evan Read's avatar
Evan Read committed
1071

1072 1073 1074 1075
  </dd>
</dl>
```

1076
<!--
Marcel Amirault's avatar
Marcel Amirault committed
1077
The example below uses HTML to force correct rendering on docs.gitlab.com,
1078
Markdown is fine in GitLab.
1079
-->
1080 1081 1082

<dl>
  <dt>Markdown in HTML</dt>
1083
  <dd>Does *not* work **very** well. HTML tags work, in most cases.</dd>
1084 1085 1086

  <dt>Markdown in HTML</dt>
  <dd>
Evan Read's avatar
Evan Read committed
1087

1088
  Does <em>not</em> work <b>very</b> well. HTML tags work, in most cases.
Evan Read's avatar
Evan Read committed
1089

1090
  </dd>
1091 1092
</dl>

1093
#### Details and summary
1094

Amy Qualls's avatar
Amy Qualls committed
1095 1096
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).
1097 1098 1099

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)
Amy Qualls's avatar
Amy Qualls committed
1100
tags. For example, collapse a long log file so it takes up less screen space.
1101 1102 1103 1104

```html
<p>
<details>
1105
<summary>Click this to collapse/fold.</summary>
1106

1107
These details <em>remain</em> <strong>hidden</strong> until expanded.
1108 1109 1110 1111 1112 1113

<pre><code>PASTE LOGS HERE</code></pre>

</details>
</p>
```
1114 1115 1116

<p>
<details>
1117
<summary>Click this to collapse/fold.</summary>
1118

1119
These details <em>remain</em> <strong>hidden</strong> until expanded.
1120 1121

<pre><code>PASTE LOGS HERE</code></pre>
1122

1123 1124 1125
</details>
</p>

1126 1127
---

Amy Qualls's avatar
Amy Qualls committed
1128
Markdown inside these tags is also supported.
1129

1130
NOTE:
1131 1132 1133 1134
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">`.

1135 1136
Remember to leave a blank line after the `</summary>` tag and before the `</details>` tag,
as shown in the example:
1137

1138
````html
1139
<details>
1140
<summary>Click this to collapse/fold.</summary>
1141

1142
These details _remain_ **hidden** until expanded.
1143

1144
```
1145
PASTE LOGS HERE
1146
```
1147

1148
</details>
1149
````
1150

1151 1152
<!--
The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown
1153
works correctly in GitLab.
1154
-->
1155

1156
<details>
1157
<summary>Click this to collapse/fold.</summary>
1158

1159
These details <em>remain</em> <b>hidden</b> until expanded.
1160

1161
<pre><code>PASTE LOGS HERE</code></pre>
1162 1163

</details>
1164

1165
### Line breaks
1166

1167
A line break is inserted (a new paragraph starts) if the previous text is
1168
ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only
1169
use one newline (hit <kbd>Enter</kbd> once), the next sentence remains part of the
Amy Qualls's avatar
Amy Qualls committed
1170
same paragraph. Use this approach if you want to keep long lines from wrapping, and keep
1171
them editable:
1172

1173 1174
```markdown
Here's a line for us to start with.
1175

1176
This longer line is separated from the one above by two newlines, so it is a *separate paragraph*.
1177

1178 1179 1180 1181
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*.
1182 1183
```

1184
Here's a line for us to start with.
1185

1186
This longer line is separated from the one above by two newlines, so it is a *separate paragraph*.
1187

1188 1189 1190 1191
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*.
1192

1193
#### Newlines
1194

1195
GFM adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/).
1196

1197 1198
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).
1199

Amy Qualls's avatar
Amy Qualls committed
1200
Need more control over line breaks or soft returns? Add a single line break
1201
by ending a line with a backslash, or two or more spaces. Two newlines in a row create a new
1202
paragraph, with a blank line in between:
1203

1204 1205 1206 1207 1208 1209 1210 1211 1212 1213
```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.
```
1214

1215
### Links
1216

1217
There are two ways to create links, inline-style and reference-style:
Simon Hardt's avatar
Simon Hardt committed
1218

1219 1220 1221 1222 1223
<!--
Do not edit the following codeblock. It uses HTML to skip the Vale ReferenceLinks test.
-->

<pre class="highlight"><code>- This is an [inline-style link](https://www.google.com)
1224 1225 1226
- This is a [link to a repository file in the same directory](index.md)
- This is a [relative link to a readme one directory higher](../README.md)
- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
1227

1228
Using header ID anchors:
1229

1230
- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
1231
- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
1232

1233
Using references:
1234

1235 1236 1237
- This is a [reference-style link, see below][Arbitrary case-insensitive reference text]
- You can [use numbers for reference-style link definitions, see below][1]
- Or leave it empty and use the [link text itself][], see below.
1238

1239
Some text to show that the reference links can follow later.
Simon Hardt's avatar
Simon Hardt committed
1240

1241 1242 1243 1244
&#91;arbitrary case-insensitive reference text]: https://www.mozilla.org/en-US/
&#91;1]: https://slashdot.org
&#91;link text itself]: https://www.reddit.com
</code></pre>
1245

1246 1247
- This is an [inline-style link](https://www.google.com)
- This is a [link to a repository file in the same directory](index.md)
1248
- This is a [relative link to a README one directory higher](../README.md)
1249
- This is a [link that also has title text](https://www.google.com "This link takes you to Google!")
1250

1251
Using header ID anchors:
1252

1253
- This links to [a section on a different Markdown page, using a "#" and the header ID](index.md#overview)
1254
- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links)
1255

1256
Using references:
1257

1258 1259 1260 1261
<!--
The example below uses in-line links to pass the Vale ReferenceLinks test.
Do not change to reference style links.
-->
1262

1263 1264 1265
- This is a [reference-style link, see below](https://www.mozilla.org/en-US/)
- You can [use numbers for reference-style link definitions, see below](https://slashdot.org)
- Or leave it empty and use the [link text itself](https://www.reddit.com), see below.
1266

1267
Some text to show that the reference links can follow later.
1268

1269
NOTE:
1270
Relative links do not allow the referencing of project files in a wiki
1271 1272
page, or a wiki page in a project file. The reason for this is that a wiki is always
in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)`
1273
points the link to `wikis/style` only when the link is inside of a wiki Markdown file.
1274

1275
#### URL auto-linking
1276

1277
GFM auto-links almost any URL you put into your text:
1278

1279
```markdown
1280
- https://www.google.com
1281
- https://www.google.com
1282 1283
- ftp://ftp.us.debian.org/debian/
- smb://foo/bar/baz
1284
- irc://irc.freenode.net/
1285
- http://localhost:3000
1286 1287
```

1288 1289
<!-- vale gitlab.Spelling = NO -->

Evan Read's avatar
Evan Read committed
1290
- <https://www.google.com>
1291
- <https://www.google.com>
Evan Read's avatar
Evan Read committed
1292 1293
- <ftp://ftp.us.debian.org/debian/>
- <smb://foo/bar/baz>
1294
- <irc://irc.freenode.net/>
Evan Read's avatar
Evan Read committed
1295
- <http://localhost:3000>
1296

1297
<!-- vale gitlab.Spelling = YES -->
1298
### Lists
1299

1300
Ordered and unordered lists can be created.
1301 1302

For an ordered list, add the number you want the list
1303
to start with, like `1.`, followed by a space, at the start of each line for ordered lists.
1304
After the first number, it does not matter what number you use, ordered lists are
1305
numbered automatically by vertical order, so repeating `1.` for all items in the
1306
same list is common. If you start with a number other than `1.`, it uses that as the first
1307
number, and count up from there.
1308

1309 1310
Examples:

1311
```markdown
1312 1313
1. First ordered list item
2. Another item
1314
   - Unordered sub-list.
1315 1316 1317 1318
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.
1319
```
1320

1321 1322 1323 1324 1325
<!--
The "2." and "4." in the example above are changed to "1." below, to match the style
standards on docs.gitlab.com.
See https://docs.gitlab.com/ee/development/documentation/styleguide.html#lists
-->
1326

1327
1. First ordered list item
1328
1. Another item
1329
   - Unordered sub-list.
1330 1331 1332
1. Actual numbers don't matter, just that it's a number
   1. Ordered sub-list
   1. Next ordered sub-list item
1333
1. And another item.
1334

1335 1336 1337
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.

1338
```markdown
1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354
Unordered lists can:

- use
- minuses

They can also:

* use
* asterisks

They can even:

+ use
+ pluses
```

1355 1356 1357 1358 1359
<!--
The "*" and "+" in the example above are changed to "-" below, to match the style
standards on docs.gitlab.com.
See https://docs.gitlab.com/ee/development/documentation/styleguide.html#lists
-->
1360 1361 1362 1363 1364 1365 1366 1367 1368 1369

Unordered lists can:

- use
- minuses

They can also:

- use
- asterisks
1370

1371
They can even:
1372

1373 1374
- use
- pluses
1375

1376
---
1377

1378 1379
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.
1380

1381
Example:
1382

1383 1384
```markdown
1. First ordered list item
1385

1386
   Second paragraph of first item.
1387

1388
1. Another item
1389
```
1390

1391
1. First ordered list item
1392

1393
   Second paragraph of first item.
1394

1395
1. Another item
1396

1397
---
1398

1399
If the paragraph of the first item is not indented with the proper number of spaces,
1400
the paragraph appears outside the list, instead of properly indented under the list item.
1401

1402
Example:
1403

1404
```markdown
1405
1. First ordered list item
1406

1407
  Paragraph of first item.
1408

1409
1. Another item
1410 1411
```

1412
1. First ordered list item
1413

1414
  Paragraph of first item.
1415

1416
1. Another item
1417 1418

### Superscripts / Subscripts
1419

Amy Qualls's avatar
Amy Qualls committed
1420 1421
CommonMark and GFM don't support the Redcarpet superscript syntax ( `x^2` ).
Use the standard HTML syntax for superscripts and subscripts:
1422

1423 1424 1425 1426
```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>.
```
1427

1428 1429
<!-- vale gitlab.Spelling = NO -->

1430 1431
The formula for water is H<sub>2</sub>O
while the equation for the theory of relativity is E = mc<sup>2</sup>.
1432

1433 1434
<!-- vale gitlab.Spelling = YES -->

1435
### Tables
1436

1437
Tables are not part of the core Markdown spec, but they are part of GFM.
1438

Evan Read's avatar
Evan Read committed
1439
1. The first line contains the headers, separated by "pipes" (`|`).
1440 1441
1. The second line separates the headers from the cells, and must contain three or more dashes.
1. The third, and any following lines, contain the cell values.
1442
   - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines,
1443 1444 1445 1446
     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.
1447

1448
Example:
1449

1450 1451
```markdown
| header 1 | header 2 | header 3 |
1452
| ---      |  ------  |----------|
1453
| cell 1   | cell 2   | cell 3   |
1454
| 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. |
1455
| cell 7   |          | cell 9   |
1456
```
1457

1458
| header 1 | header 2 | header 3 |
1459
| ---      |  ------  |----------|
1460
| cell 1   | cell 2   | cell 3   |
1461
| 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. |
1462
| cell 7   |          | cell 9   |
1463

Amy Qualls's avatar
Amy Qualls committed
1464
Additionally, you can choose the alignment of text in columns by adding colons (`:`)
1465
to the sides of the "dash" lines in the second row. This affects every cell in the column:
1466

1467 1468 1469 1470 1471 1472
```markdown
| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
| :---         | :---:    | ---:          | :----------- | :------: | ------------: |
| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
```
1473

1474 1475 1476 1477
| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned |
| :---         | :---:    | ---:          | :----------- | :------: | ------------: |
| Cell 1       | Cell 2   | Cell 3        | Cell 4       | Cell 5   | Cell 6        |
| Cell 7       | Cell 8   | Cell 9        | Cell 10      | Cell 11  | Cell 12       |
1478

Amy Qualls's avatar
Amy Qualls committed
1479
[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables),
1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496
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 |
|------|---------|
| Item1 | This is on one line |
| Item2 | This item has:<br>- Multiple items<br>- That we want listed separately |
```

| Name | Details |
|------|---------|
| Item1 | This is on one line |
| Item2 | This item has:<br>- Multiple items<br>- That we want listed separately |

Amy Qualls's avatar
Amy Qualls committed
1497
You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes,
1498 1499 1500 1501 1502 1503 1504 1505 1506
but they do not render properly on `docs.gitlab.com`:

```markdown
| header 1 | header 2 |
|----------|----------|
| cell 1   | cell 2   |
| cell 3   | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> |
```

1507 1508
#### Copy from spreadsheet and paste in Markdown

1509
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7.
1510

1511
If you're working in spreadsheet software (for example, Microsoft Excel, Google
Amy Qualls's avatar
Amy Qualls committed
1512 1513
Sheets, or Apple Numbers), GitLab creates a Markdown table when you copy-and-paste
from a spreadsheet. For example, suppose you have the
1514 1515 1516 1517 1518 1519 1520 1521 1522
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)

1523 1524
## References

1525
- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
1526
- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax)
1527
  at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown.
1528
- You can find the detailed specification for CommonMark in the [CommonMark Spec](https://spec.commonmark.org/current/).
Amy Qualls's avatar
Amy Qualls committed
1529
- The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax.