markdown.md 49.5 KB
Newer Older
1
---
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"
5
type: reference, howto
6
7
---

8
# GitLab Flavored Markdown **(FREE)**
Marin Jankovski's avatar
Marin Jankovski committed
9

10
11
12
GitLab automatically renders Markdown content. For example, when you add a comment to an issue,
you type the text in the Markdown language. When you save the issue, the text is rendered
with a set of styles. These styles are described on this page.
13

14
For example, in Markdown, an ordered list looks like this:
rubyjunkie's avatar
rubyjunkie committed
15

16
17
18
19
20
21
22
23
24
25
26
```markdown
- Cat
- Dog
- Turtle
```

When this list is rendered, it looks like this:

- Cat
- Dog
- Turtle
27

28
29
30
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.

31
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).
32
33

GitLab Flavored Markdown extends the [CommonMark specification](https://spec.commonmark.org/current/).
34
It was inspired by [GitHub Flavored Markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
35

36
37
## Where you can use GitLab Flavored Markdown

38
You can use GitLab Flavored Markdown in the following areas:
39

40
41
42
43
44
45
46
- Comments
- Issues
- Merge requests
- Milestones
- Snippets (the snippet must be named with a `.md` extension)
- Wiki pages
- Markdown documents inside repositories
47
- Epics
48

49
You can also use other rich text files in GitLab. You might have to install a dependency
50
to do so. For more information, see the [`gitlab-markup` gem project](https://gitlab.com/gitlab-org/gitlab-markup).
51

52
### Differences between GitLab Flavored Markdown and standard Markdown
53

54
55
GitLab uses standard CommonMark formatting. However, GitLab Flavored Markdown
extends standard Markdown with features made specifically for GitLab.
56

57
Features not found in standard Markdown:
58

59
- [Color chips written in `HEX`, `RGB` or `HSL`](#colors)
60
- [Diagrams and flowcharts](#diagrams-and-flowcharts)
61
- [Emoji](#emojis)
62
63
64
65
- [Front matter](#front-matter)
- [Inline diffs](#inline-diff)
- [Math equations and symbols written in LaTeX](#math)
- [Task Lists](#task-lists)
66
- [Table of Contents](#table-of-contents)
67
- [Wiki specific Markdown](#wiki-specific-markdown)
68

69
Features [extended from standard Markdown](#features-extended-from-standard-markdown):
70

71
| Standard Markdown                     | Extended Markdown in GitLab |
72
| ------------------------------------- | ------------------------- |
73
| [blockquotes](#blockquotes)           | [multi-line blockquotes](#multiline-blockquote) |
74
75
76
| [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) |
77
| [images](#images)                     | [embedded videos](#videos) and [audio](#audio) |
78
| [line breaks](#line-breaks)           | [more line break control](#newlines) |
79
80
| [links](#links)                       | [automatically linking URLs](#url-auto-linking) |

81
82
83
## Features not found in standard Markdown

The following features are not found in standard Markdown.
Evan Read's avatar
Evan Read committed
84

85
### Colors
86

87
[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colors).
88

89
You can write a color in the formats: `HEX`, `RGB`, or `HSL`.
90

91
92
93
- `HEX`: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
- `RGB`: `` `RGB[A](R, G, B[, A])` ``
- `HSL`: `` `HSL[A](H, S, L[, A])` ``
94

95
Named colors are not supported.
96

97
Colors in backticks are followed by a color indicator:
98

99
```markdown
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
- `#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)`
120

121
122
### Diagrams and flowcharts

123
124
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.
125
126

#### Mermaid
127

128
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in GitLab 10.3.
129

130
131
132
133
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.
134

135
To generate a diagram or flowchart, write your text inside the `mermaid` block:
136

137
````markdown
138
139
140
141
142
143
144
```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```
145
````
146

147
148
149
150
151
152
153
```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```
154

155
You can also include subgraphs:
156

157
````markdown
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
```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
```
174
````
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

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

193
194
#### PlantUML

195
196
To make PlantUML available in GitLab, a GitLab administrator must enable it. For more information, see the
[PlantUML & GitLab](../administration/integration/plantuml.md) page.
197

198
199
#### Kroki

200
201
To make Kroki available in GitLab, a GitLab administrator must enable it.
For more information, see the [Kroki integration](../administration/integration/kroki.md) page.
202

203
### Emojis
204

205
[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis).
206

207
```markdown
208
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
209

210
:zap: You can use emoji anywhere GitLab Flavored Markdown is supported. :v:
211

212
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.
213

214
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.
215

216
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
217
```
218

219
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:
220

221
<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 GitLab Flavored Markdown 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">
222

223
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.
224

225
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.
226

227
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">
228

229
#### Emojis and your operating system
230

231
232
The previous emoji example uses hard-coded images. Rendered emojis
in GitLab may be different depending on the OS and browser used.
233

234
235
Most emojis are natively supported on macOS, Windows, iOS, Android, and fall back on image-based
emojis where there is no support.
236

237
238
<!-- vale gitlab.Spelling = NO -->

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

243
244
<!-- vale gitlab.Spelling = YES -->

245
### Front matter
246

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

249
Front matter is metadata included at the beginning of a Markdown document, preceding
250
the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/),
251
[Hugo](https://gohugo.io/content-management/front-matter/), and many other applications.
252

253
When you view a Markdown file rendered by GitLab, front matter is displayed as-is,
254
255
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
256
[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md).
257

258
In GitLab, front matter is used only in Markdown files and wiki pages, not the other
259
places where Markdown formatting is supported. It must be at the very top of the document
260
and must be between delimiters.
261

262
The following delimiters are supported:
263

264
- YAML (`---`):
265

266
  ```yaml
267
268
269
270
271
  ---
  title: About Front Matter
  example:
  language: yaml
  ---
272
  ```
273

274
- TOML (`+++`):
275

276
  ```toml
277
278
279
280
281
  +++
  title = "About Front Matter"
  [example]
  language = "toml"
  +++
282
  ```
283

284
- JSON (`;;;`):
285

286
  ```json
287
288
289
290
291
292
293
294
  ;;;
  {
    "title": "About Front Matter"
    "example": {
      "language": "json"
    }
  }
  ;;;
295
  ```
296

297
298
299
300
301
302
303
304
305
306
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",
);
---
307
308
```

309
### Inline diff
310

311
[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff).
312

313
With inline diff tags, you can display `{+ additions +}` or `[- deletions -]`.
314

315
The wrapping tags can be either curly braces or square brackets:
316

317
318
319
320
321
```markdown
- {+ addition 1 +}
- [+ addition 2 +]
- {- deletion 3 -}
- [- deletion 4 -]
322
323
```

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

326
---
327

328
However, you cannot mix the wrapping tags:
329

330
331
332
333
334
```markdown
- {+ addition +]
- [+ addition +}
- {- deletion -]
- [- deletion -}
335
```
336

337
If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a
338
backslash `\`. Otherwise the diff highlight does not render correctly:
339
340
341
342
343
344
345

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

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

348
### Math
349

350
[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math).
351

352
Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX).
353

354
355
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
356
on a separate line:
357

358
````markdown
359
This math is inline $`a^2+b^2=c^2`$.
360

361
This is on a separate line:
362

363
364
```math
a^2+b^2=c^2
Marcia Ramos's avatar
Marcia Ramos committed
365
```
366
````
367

368
This math is inline $`a^2+b^2=c^2`$.
369

370
This is on a separate line
371

372
373
374
```math
a^2+b^2=c^2
```
375

376
_KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._
377

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

381
### Task lists
Vinnie Okada's avatar
Vinnie Okada committed
382

383
[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists).
384

385
You can add task lists anywhere Markdown is supported.
Vinnie Okada's avatar
Vinnie Okada committed
386

387
388
389
390
391
- 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:
392
393

```markdown
394
395
- [x] Completed task
- [ ] Incomplete task
396
397
398
  - [ ] Sub-task 1
  - [x] Sub-task 2
  - [ ] Sub-task 3
399

400
401
402
403
1. [x] Completed task
1. [ ] Incomplete task
   1. [ ] Sub-task 1
   1. [x] Sub-task 2
Vinnie Okada's avatar
Vinnie Okada committed
404
405
```

406
![Task list as rendered by GitLab](img/completed_tasks_v13_3.png)
407

408
### Table of contents
409

410
411
412
A table of contents is an unordered list that links to subheadings in the document.

To add a table of contents to a Markdown file, wiki page, issue request, or merge request
413
description, add either the `[[_TOC_]]` or `[TOC]` tag on its own line.
414

415
416
417
418
NOTE:
You can add a table of contents to issues and merge requests, but you can't add one
to notes or comments.

419
```markdown
420
421
This is an intro sentence to my Wiki page.

422
[[_TOC_]]
423
424
425
426
427
428
429
430

## My first heading

First section content.

## My second heading

Second section content.
431
432
```

433
![Preview of an auto-generated table of contents in a Wiki](img/markdown_toc_preview_v12_9.png)
434

435
### Wiki-specific Markdown
436

437
The following topics show how links inside wikis behave.
Vinnie Okada's avatar
Vinnie Okada committed
438

439
#### Wiki - direct page link
440

441
442
A direct page link includes the slug for a page that points to that page,
at the base level of the wiki.
443

444
This example links to a `documentation` page at the root of your wiki:
445

446
447
448
```markdown
[Link to Documentation](documentation)
```
449

450
#### Wiki - direct file link
451

452
A direct file link points to a file extension for a file, relative to the current page.
453

454
455
If the following example is on a page at `<your_wiki>/documentation/related`,
it links to `<your_wiki>/documentation/file.md`:
456

457
458
459
```markdown
[Link to File](file.md)
```
460

461
#### Wiki - hierarchical link
462

463
A hierarchical link can be constructed relative to the current wiki page by using `./<page>`,
464
`../<page>`, and so on.
465

466
467
If this example is on a page at `<your_wiki>/documentation/main`,
it links to `<your_wiki>/documentation/related`:
468

469
```markdown
470
[Link to Related Page](related)
471
```
472

473
474
If this example is on a page at `<your_wiki>/documentation/related/content`,
it links to `<your_wiki>/documentation/main`:
475

476
477
478
```markdown
[Link to Related Page](../main)
```
479

480
481
If this example is on a page at `<your_wiki>/documentation/main`,
it links to `<your_wiki>/documentation/related.md`:
482

483
```markdown
484
[Link to Related Page](related.md)
485
```
486

487
488
If this example is on a page at `<your_wiki>/documentation/related/content`,
it links to `<your_wiki>/documentation/main.md`:
489

490
491
492
```markdown
[Link to Related Page](../main.md)
```
493

494
#### Wiki - root link
495

496
A root link starts with a `/` and is relative to the wiki root.
497

498
This example links to `<wiki_root>/documentation`:
499

500
501
502
```markdown
[Link to Related Page](/documentation)
```
503

504
This example links to `<wiki_root>/miscellaneous.md`:
505

506
507
508
```markdown
[Link to Related Page](/miscellaneous.md)
```
509

510
511
512
513
## 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
514
that reference into a link so you can navigate between them. All references to projects should use the
515
**project slug** rather than the project name.
516
517
518
519
520
521
522
523
524
525
526

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:

| references                      | input                      | cross-project reference                 | shortcut inside same namespace |
| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- |
| specific user                   | `@user_name`               |                                         |                                |
| specific group                  | `@group_name`              |                                         |                                |
| entire team                     | `@all`                     |                                         |                                |
527
| project                         | `namespace/project>`       |                                         |                                |
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
| issue                           | ``#123``                   | `namespace/project#123`                 | `project#123`                  |
| merge request                   | `!123`                     | `namespace/project!123`                 | `project!123`                  |
| snippet                         | `$123`                     | `namespace/project$123`                 | `project$123`                  |
| epic **(ULTIMATE)**             | `&123`                     | `group1/subgroup&123`                   |                                |
| vulnerability **(ULTIMATE)** (1)| `[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`            |

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

560
561
### Embedding metrics in GitLab Flavored Markdown

562
563
Metric charts can be embedded in GitLab Flavored Markdown. Read
[Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details.
564

565
## Features extended from standard Markdown
566

567
All standard Markdown formatting should work as expected in GitLab. Some standard
568
functionality is extended with additional features, without affecting the standard usage.
569
If a functionality is extended, the new option is listed as a sub-section.
570

571
### Blockquotes
572

573
Use a blockquote to highlight information, such as a side note. It's generated
574
by starting the lines of the blockquote with `>`:
575

576
```markdown
577
> Blockquotes help you emulate reply text.
578
> This line is part of the same quote.
579

580
Quote break.
581

582
> 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.
583
```
584

585
> Blockquotes help you emulate reply text.
586
> This line is part of the same quote.
587

588
Quote break.
blackst0ne's avatar
blackst0ne committed
589

590
> 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.
blackst0ne's avatar
blackst0ne committed
591

592
#### Multiline blockquote
blackst0ne's avatar
blackst0ne committed
593

594
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).
blackst0ne's avatar
blackst0ne committed
595

596
GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes
597
fenced by `>>>`:
blackst0ne's avatar
blackst0ne committed
598

599
```markdown
600
601
>>>
If you paste a message from somewhere else
blackst0ne's avatar
blackst0ne committed
602

603
that spans multiple lines,
blackst0ne's avatar
blackst0ne committed
604

605
606
you can quote that without having to manually prepend `>` to every line!
>>>
607
```
blackst0ne's avatar
blackst0ne committed
608

609
610
>>>
If you paste a message from somewhere else
blackst0ne's avatar
blackst0ne committed
611

612
that spans multiple lines,
613

614
615
you can quote that without having to manually prepend `>` to every line!
>>>
616

617
### Code spans and blocks
618

619
You can highlight anything that should be viewed as code and not standard text.
620

621
Inline code is highlighted with single backticks `` ` ``:
622

623
624
625
```markdown
Inline `code` has `back-ticks around` it.
```
626

627
Inline `code` has `back-ticks around` it.
628

629
---
630

631
632
633
634
635
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.
636

637
638
````markdown
```python
639
640
641
642
643
def function():
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s
```
644

645
646
647
    Using 4 spaces
    is like using
    3-backtick fences.
648
````
649

650
```plaintext
651
652
653
~~~
Tildes are OK too.
~~~
654
655
```

656
The three examples above render as:
657

658
```python
659
660
661
662
663
def function():
    #indenting works just fine in the fenced code block
    s = "Python code"
    print s
```
664

665
```plaintext
666
667
668
669
Using 4 spaces
is like using
3-backtick fences.
```
670

671
```plaintext
672
Tildes are OK too.
673
```
674

675
#### Colored code and syntax highlighting
676

677
If this section isn't rendered correctly,
678
[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting).
679

680
681
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
682
[Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
683
Syntax highlighting is supported only in code blocks, so you can't highlight inline code.
684

685
686
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 (`~~~`):
687

688
````markdown
689
690
691
692
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
693

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

701
702
703
704
705
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
706
707

```
708
709
710
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
711
```
712
````
713

714
The four examples above render as:
715

716
717
718
719
```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
720

721
722
723
724
725
726
727
728
729
730
731
732
733
```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
```

734
```plaintext
735
736
737
738
No language indicated, so no syntax highlighting.
s = "There is no highlighting for this."
But let's throw in a <b>tag</b>.
```
739

740
### Emphasis
741

742
There are multiple ways to emphasize text in Markdown. You can italicize, bold, strikethrough,
743
and combine these emphasis styles together.
744
Strikethrough is not part of the core Markdown standard, but is part of GitLab Flavored Markdown.
745

746
747
Examples:

748
```markdown
749
750
Emphasis, aka italics, with *asterisks* or _underscores_.

751
Strong emphasis, aka bold, with double **asterisks** or __underscores__.
752

Simon Hardt's avatar
Simon Hardt committed
753
Combined emphasis with **asterisks and _underscores_**.
754
755
756
757
758
759

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

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

760
Strong emphasis, aka bold, with double **asterisks** or __underscores__.
761
762
763
764
765

Combined emphasis with **asterisks and _underscores_**.

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

766
#### Multiple underscores in words and mid-word emphasis
767

768
If this section isn't rendered correctly,
769
[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words).
770

771
772
Avoid italicizing a portion of a word, especially when you're
dealing with code and names that often appear with multiple underscores.
773
GitLab Flavored Markdown extends the standard Markdown standard by ignoring multiple underlines in words,
774
to allow better rendering of Markdown documents discussing code:
775

776
```markdown
777
778
779
780
781
perform_complicated_task

do_this_and_do_that_and_another_thing

but_emphasis is_desired _here_
782
783
```

784
perform_complicated_task
Evan Read's avatar
Evan Read committed
785

786
do_this_and_do_that_and_another_thing
787

788
but_emphasis is_desired _here_
789

790
---
791

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

794
```markdown
795
perform*complicated*task
Evan Read's avatar
Evan Read committed
796

797
798
799
800
do*this*and*do*that*and*another thing
```

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

802
803
804
do*this*and*do*that*and*another thing

### Footnotes
805

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

808
809
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
the note content.
810

811
812
Regardless of the tag names, the relative order of the reference tags determines the rendered
numbering.
813

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

818
819
820
821
822
<!--
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]
823

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

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

828
829
&#91;^footnote-42]: This is another footnote.
</code></pre>
830

831
A footnote reference tag looks like this:[^1]
rubyjunkie's avatar
rubyjunkie committed
832

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

835
836
837
838
839
840
<!--
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.
841

842
 [^footnote-42]: This is another footnote.
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860

### Headers

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

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

Alt-H1
======

Alt-H2
------
861
862
```

863
#### Header IDs and links
864

865
GitLab Flavored Markdown extends the standard Markdown standard so that all Markdown-rendered headers automatically
866
get IDs, which can be linked to, except in comments.
867

868
869
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.
rubyjunkie's avatar
rubyjunkie committed
870

871
The IDs are generated from the content of the header according to the following rules:
872

873
1. All text is converted to lowercase.
874
1. All non-word text (such as punctuation or HTML) is removed.
875
876
877
878
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.
879

880
881
Example: