markdown.md 25.8 KB
Newer Older
1 2
# Markdown

3
## GitLab Flavored Markdown (GFM)
4

5 6 7 8 9 10 11
> **Note:**
Not all of the GitLab-specific extensions to Markdown that are described in
this document currently work on our documentation website.
>
For the best result, we encourage you to check this document out as rendered
by GitLab: [markdown.md]

12
_GitLab uses the [Redcarpet Ruby library][redcarpet] for Markdown processing._
13

14
GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/).
15

16
You can use GFM in the following areas:
17

18 19 20 21
- comments
- issues
- merge requests
- milestones
22
- snippets (the snippet must be named with a `.md` extension)
23
- wiki pages
24
- markdown documents inside the repository
25

26 27
You can also use other rich text files in GitLab. You might have to install a
dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information.
28

29
### Newlines
30

31
> If this is not rendered correctly, see
32
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines
33

34
GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p).
35

36
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.
37
Line-breaks, or softreturns, are rendered if you end a line with two or more spaces:
38

39 40 41
[//]: # (Do *NOT* remove the two ending whitespaces in the following line.)
[//]: # (They are needed for the Markdown text to render correctly.)
    Roses are red [followed by two or more spaces]  
42 43
    Violets are blue

44 45
    Sugar is sweet

46 47 48
[//]: # (Do *NOT* remove the two ending whitespaces in the following line.)
[//]: # (They are needed for the Markdown text to render correctly.)
Roses are red  
49
Violets are blue
50

51 52
Sugar is sweet

53
### Multiple underscores in words
54

55
> If this is not rendered correctly, see
56
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words
57 58

It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words:
59 60

    perform_complicated_task
61

62 63
    do_this_and_do_that_and_another_thing

64
perform_complicated_task
65

66 67
do_this_and_do_that_and_another_thing

68
### URL auto-linking
69

70
> If this is not rendered correctly, see
71
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking
72 73

GFM will autolink almost any URL you copy and paste into your text:
74

75
    * https://www.google.com
76 77 78 79 80 81
    * https://google.com/
    * ftp://ftp.us.debian.org/debian/
    * smb://foo/bar/baz
    * irc://irc.freenode.net/gitlab
    * http://localhost:3000

82
* https://www.google.com
83 84 85 86 87
* https://google.com/
* ftp://ftp.us.debian.org/debian/
* smb://foo/bar/baz
* irc://irc.freenode.net/gitlab
* http://localhost:3000
88

89
### Multiline Blockquote
90

91
> If this is not rendered correctly, see
92
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote
93

94
On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines,
95
GFM supports multiline blockquotes fenced by <code>>>></code>:
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122

```no-highlight
>>>
If you paste a message from somewhere else

that

spans

multiple lines,

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

>>>
If you paste a message from somewhere else

that

spans

multiple lines,

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

123
### Code and Syntax Highlighting
124

125
> If this is not rendered correctly, see
126
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting
127

128 129
_GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a
list of supported languages visit the Rouge website._
130

131 132 133
Blocks of code are either fenced by lines with three back-ticks <code>```</code>,
or are indented with four spaces. Only the fenced code blocks support syntax
highlighting:
134 135 136 137 138 139 140 141 142 143 144 145 146

```no-highlight
Inline `code` has `back-ticks around` it.
```

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

Example:

    ```javascript
    var s = "JavaScript syntax highlighting";
    alert(s);
    ```
147

148 149 150 151 152 153
    ```python
    def function():
        #indenting works just fine in the fenced code block
        s = "Python syntax highlighting"
        print s
    ```
154

155 156 157 158 159 160 161
    ```ruby
    require 'redcarpet'
    markdown = Redcarpet.new("Hello World!")
    puts markdown.to_html
    ```

    ```
162
    No language indicated, so no syntax highlighting.
163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
    s = "There is no highlighting for this."
    But let's throw in a <b>tag</b>.
    ```

becomes:

```javascript
var s = "JavaScript syntax highlighting";
alert(s);
```

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

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

193
### Inline Diff
194

195
> If this is not rendered correctly, see
196
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff
197

198 199 200 201
With inline diffs tags you can display {+ additions +} or [- deletions -].

The wrapping tags can be either curly braces or square brackets [+ additions +] or {- deletions -}.

202 203 204 205 206 207 208 209 210
Examples:

```
- {+ additions +}
- [+ additions +]
- {- deletions -}
- [- deletions -]
```

211 212
However the wrapping tags cannot be mixed as such:

213
```
214 215 216 217
- {+ additions +]
- [+ additions +}
- {- deletions -]
- [- deletions -}
218
```
219

220
### Emoji
221

222
> If this is not rendered correctly, see
223
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji
224

225
	Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
226

227
	:zap: You can use emoji anywhere GFM is supported. :v:
228

229
	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 will :heart: you for that.
230

231
	If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes.
232

233
	Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
234

235
Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you:
236

237
:zap: You can use emoji anywhere GFM is supported. :v:
238

239
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 will :heart: you for that.
240

241
If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes.
242

243
Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
244

245
### Special GitLab References
246

247
GFM recognizes special references.
248

249
You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project.
250

251 252 253 254
GFM will turn that reference into a link so you can navigate between them easily.

GFM will recognize the following:

255 256 257 258 259
| input                      | references                      |
|:---------------------------|:--------------------------------|
| `@user_name`               | specific user                   |
| `@group_name`              | specific group                  |
| `@all`                     | entire team                     |
260
| `#12345`                   | issue                           |
261 262 263 264 265
| `!123`                     | merge request                   |
| `$123`                     | snippet                         |
| `~123`                     | label by ID                     |
| `~bug`                     | one-word label by name          |
| `~"feature request"`       | multi-word label by name        |
266
| `%123`                     | project milestone by ID         |
267 268 269 270 271 272
| `%v1.23`                   | one-word milestone by name      |
| `%"release candidate"`     | multi-word milestone by name    |
| `9ba12248`                 | specific commit                 |
| `9ba12248...b19a04f5`      | commit range comparison         |
| `[README](doc/README)`     | repository file references      |
| `[README](doc/README#L13)` | repository file line references |
273 274 275 276

GFM also recognizes certain cross-project references:

| input                                   | references              |
277
|:----------------------------------------|:------------------------|
278 279
| `namespace/project#123`                 | issue                   |
| `namespace/project!123`                 | merge request           |
280
| `namespace/project%123`                 | project milestone       |
281 282 283
| `namespace/project$123`                 | snippet                 |
| `namespace/project@9ba12248`            | specific commit         |
| `namespace/project@9ba12248...b19a04f5` | commit range comparison |
284
| `namespace/project~"Some label"`        | issues with given label |
285

286 287 288 289 290 291
It also has a shorthand version to reference other projects from the same namespace:

| input                         | references              |
|:------------------------------|:------------------------|
| `project#123`                 | issue                   |
| `project!123`                 | merge request           |
292
| `project%123`                 | project milestone       |
293 294 295 296 297
| `project$123`                 | snippet                 |
| `project@9ba12248`            | specific commit         |
| `project@9ba12248...b19a04f5` | commit range comparison |
| `project~"Some label"`        | issues with given label |

298
### Task Lists
299

300
> If this is not rendered correctly, see
301
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists
302

303
You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so:
304 305

```no-highlight
306 307 308 309 310
- [x] Completed task
- [ ] Incomplete task
    - [ ] Sub-task 1
    - [x] Sub-task 2
    - [ ] Sub-task 3
311 312
```

313 314 315 316 317 318
- [x] Completed task
- [ ] Incomplete task
    - [ ] Sub-task 1
    - [x] Sub-task 2
    - [ ] Sub-task 3

319 320 321 322 323 324 325 326 327 328 329 330 331 332
Tasks formatted as ordered lists are supported as well:

```no-highlight
1. [x] Completed task
1. [ ] Incomplete task
    1. [ ] Sub-task 1
    1. [x] Sub-task 2
```

1. [x] Completed task
1. [ ] Incomplete task
    1. [ ] Sub-task 1
    1. [x] Sub-task 2

333
Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes.
334

335
### Videos
336

337
> If this is not rendered correctly, see
338
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos
339

340 341
Image tags with a video extension are automatically converted to a video player.

342
The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`.
343 344 345

    Here's a sample video:

346
    ![Sample Video](img/markdown_video.mp4)
347 348 349

Here's a sample video:

350
![Sample Video](img/markdown_video.mp4)
351

352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385
### Math

> If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math

It is possible to have math written with the LaTeX syntax rendered using [KaTeX][katex].

Math written inside ```$``$``` will be rendered inline with the text.

Math written inside triple back quotes, with the language declared as `math`, will be rendered on a separate line.

Example:

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

    This is on a separate line
    ```math
    a^2+b^2=c^2
    ```

Becomes:

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

This is on a separate line
```math
a^2+b^2=c^2
```

_Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._

>**Note:**
This also works for the asciidoctor `:stem: latexmath`. For details see the [asciidoctor user manual][asciidoctor-manual].

386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424
### Colors

> If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors

It is possible to have color written in HEX, RGB or HSL format rendered with a color indicator.

Color written inside backticks will be followed by a color "chip".

Examples:

    `#F00`
    `#F00A`
    `#FF0000`
    `#FF0000AA`
    `RGB(0,255,0)`
    `RGB(0%,100%,0%)`
    `RGBA(0,255,0,0.7)`
    `HSL(540,70%,50%)`
    `HSLA(540,70%,50%,0.7)`

Becomes:

`#F00`  
`#F00A`  
`#FF0000`  
`#FF0000AA`  
`RGB(0,255,0)`  
`RGB(0%,100%,0%)`  
`RGBA(0,255,0,0.7)`  
`HSL(540,70%,50%)`  
`HSLA(540,70%,50%,0.7)`  

#### Supported formats:

* HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` ``
* RGB: `` `RGB[A](R, G, B[, A])` ``
* HSL: `` `HSL[A](H, S, L[, A])` ``

blackst0ne's avatar
blackst0ne committed
425 426
### Mermaid

427 428 429
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in
GitLab 10.3.

blackst0ne's avatar
blackst0ne committed
430 431 432
> If this is not rendered correctly, see
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid

433
It is possible to generate diagrams and flowcharts from text using [Mermaid][mermaid].
blackst0ne's avatar
blackst0ne committed
434

435
In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block.
blackst0ne's avatar
blackst0ne committed
436

437
Example:
blackst0ne's avatar
blackst0ne committed
438 439 440 441 442 443 444

    ```mermaid
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
445
    ```
blackst0ne's avatar
blackst0ne committed
446 447 448 449 450 451 452 453 454

Becomes:

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
455
```
blackst0ne's avatar
blackst0ne committed
456 457 458

For details see the [Mermaid official page][mermaid].

459
## Standard Markdown
460

461
### Headers
462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479

```no-highlight
# H1
## H2
### H3
#### H4
##### H5
###### H6

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

Alt-H1
======

Alt-H2
------
```

480 481
### Header IDs and links

482
All Markdown-rendered headers automatically get IDs, except in comments.
483 484 485 486 487

On hover a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else.

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

488 489 490 491 492
1. All text is converted to lowercase
1. All non-word text (e.g., punctuation, HTML) is removed
1. All spaces are converted to hyphens
1. Two or more hyphens in a row are converted to one
1. If a header with the same ID has already been generated, a unique
493
   incrementing number is appended, starting at 1.
494 495 496 497

For example:

```
498 499 500 501 502
# 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
503 504
```

505
Would generate the following link IDs:
506

507 508 509
1. `this-header-has-spaces-in-it`
1. `this-header-has-a-in-it`
1. `this-header-has-unicode-in-it-한글`
510
1. `this-header-has-spaces-in-it`
511
1. `this-header-has-spaces-in-it-1`
512

513
Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.
514

515
### Emphasis
516 517 518 519 520 521

```no-highlight
Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Simon Hardt's avatar
Simon Hardt committed
522
Combined emphasis with **asterisks and _underscores_**.
523 524 525 526 527 528 529 530 531 532 533 534

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

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

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

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

535
### Lists
536 537 538 539

```no-highlight
1. First ordered list item
2. Another item
540
  * Unordered sub-list.
541 542
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
543 544
4. And another item.

545 546 547 548 549 550 551
* Unordered list can use asterisks
- Or minuses
+ Or pluses
```

1. First ordered list item
2. Another item
552
  * Unordered sub-list.
553 554
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
555 556
4. And another item.

557 558 559 560
* Unordered list can use asterisks
- Or minuses
+ Or pluses

561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590
If a list item contains multiple paragraphs,
each subsequent paragraph should be indented with four spaces.

```no-highlight
1.  First ordered list item

    Second paragraph of first item.
2.  Another item
```

1.  First ordered list item

    Second paragraph of first item.
2.  Another item

If the second paragraph isn't indented with four spaces,
the second list item will be incorrectly labeled as `1`.

```no-highlight
1. First ordered list item

   Second paragraph of first item.
2. Another item
```

1. First ordered list item

   Second paragraph of first item.
2. Another item

591
### Links
592

593
There are two ways to create links, inline-style and reference-style.
594 595 596 597 598

    [I'm an inline-style link](https://www.google.com)

    [I'm a reference-style link][Arbitrary case-insensitive reference text]

599
    [I'm a relative reference to a repository file](LICENSE)
600

601
    [I am an absolute reference within the repository](/doc/user/markdown.md)
602

603
    [I link to the Milestones page](/../milestones)
604 605 606 607 608 609 610 611 612

    [You can use numbers for reference-style link definitions][1]

    Or leave it empty and use the [link text itself][]

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

    [arbitrary case-insensitive reference text]: https://www.mozilla.org
    [1]: http://slashdot.org
613
    [link text itself]: https://www.reddit.com
614

615 616 617 618
>**Note:**
Relative links do not allow referencing project files in a wiki page or wiki
page in a project file. The reason for this is that, in GitLab, wiki is always
a separate Git repository. For example, `[I'm a reference-style link](style)`
619 620
will point the link to `wikis/style` when the link is inside of a wiki markdown file.

621
### Images
622 623 624

    Here's our logo (hover to see the title text):

625
    Inline-style:
626
    ![alt text](img/markdown_logo.png)
627

628
    Reference-style:
629
    ![alt text1][logo]
630

631
    [logo]: img/markdown_logo.png
632

633
Here's our logo:
634

635
Inline-style:
636

637
![alt text](img/markdown_logo.png)
638

639
Reference-style:
640

641 642
![alt text][logo]

643
[logo]: img/markdown_logo.png
644

645
### Blockquotes
646 647 648 649 650 651 652

```no-highlight
> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

653
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
654 655 656 657 658 659 660
```

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

661
> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.
662

663
### Inline HTML
664

665
You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
666

667
See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes.  In addition to the default `SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements.
668

669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686
```no-highlight
<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>
```

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

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>

687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710
#### Details and Summary

Content can be collapsed using HTML's [`<details>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [`<summary>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. This is especially useful for collapsing long logs so they take up less screen space.

<p>
<details>
<summary>Click me to collapse/fold.</summary>
These details will remain hidden until expanded.

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

**Note:** Unfortunately Markdown is not supported inside these tags, as described by the [markdown specification](https://daringfireball.net/projects/markdown/syntax#html). You can work around this by using HTML, for example you can use `<pre><code>` tags instead of [code fences](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting).

```html
<details>
<summary>Click me to collapse/fold.</summary>
These details will remain hidden until expanded.

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

711
### Horizontal Rule
712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742

```
Three or more...

---

Hyphens

***

Asterisks

___

Underscores
```

Three or more...

---

Hyphens

***

Asterisks

___

Underscores

743
### Line Breaks
744

745
My basic recommendation for learning how line breaks work is to experiment and discover -- hit &lt;Enter&gt; once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. "Markdown Toggle" is your friend.
746 747 748 749 750 751 752 753 754

Here are some things to try out:

```
Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
Simon Hardt's avatar
Simon Hardt committed
755 756
This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.

757
This line is also a separate paragraph, and...  
Simon Hardt's avatar
Simon Hardt committed
758
This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)
759 760

spaces.
761 762 763 764 765 766
```

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

Simon Hardt's avatar
Simon Hardt committed
767 768 769
This line is also a separate paragraph, but...
This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.

770
This line is also a separate paragraph, and...  
Simon Hardt's avatar
Simon Hardt committed
771
This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)
772

773 774
spaces.

775
### Tables
776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792

Tables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them.

```
| header 1 | header 2 |
| -------- | -------- |
| cell 1   | cell 2   |
| cell 3   | cell 4   |
```

Code above produces next output:

| header 1 | header 2 |
| -------- | -------- |
| cell 1   | cell 2   |
| cell 3   | cell 4   |

793 794 795 796
**Note**

The row of dashes between the table header and body must have at least three dashes in each column.

797 798 799 800 801 802 803 804 805 806 807 808 809 810
By including colons in the header row, you can align the text within that column:

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

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

811
### Footnotes
812 813

```
814 815
You can add footnotes to your text as follows.[^2]
[^2]: This is my awesome footnote.
816
```
817

818 819
You can add footnotes to your text as follows.[^2]

820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853
## Wiki-specific Markdown

The following examples show how links inside wikis behave.

### Wiki - Direct page link

A link which just includes the slug for a page will point to that page,
_at the base level of the wiki_.

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

```markdown
[Link to Documentation](documentation)
```

### Wiki - Direct file link

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

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

```markdown
[Link to File](file.md)
```

### Wiki - Hierarchical link

A link can be constructed relative to the current wiki page using `./<page>`,
`../<page>`, etc.

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

854 855 856
    ```markdown
    [Link to Related Page](./related)
    ```
857 858 859 860

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

861 862 863
    ```markdown
    [Link to Related Page](../main)
    ```
864 865 866 867

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

868 869 870
    ```markdown
    [Link to Related Page](./related.md)
    ```
871 872 873 874

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

875 876 877
    ```markdown
    [Link to Related Page](../main.md)
    ```
878 879 880 881 882 883 884

### Wiki - Root link

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

- This snippet links to `<wiki_root>/documentation`:

885 886 887
    ```markdown
    [Link to Related Page](/documentation)
    ```
888 889 890

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

891 892 893 894
    ```markdown
    [Link to Related Page](/miscellaneous.md)
    ```

895 896
## References

897
- This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
898
- The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
899
- [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown.
900

901 902 903
[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com
[^2]: This is my awesome footnote.

904
[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md
blackst0ne's avatar
blackst0ne committed
905
[mermaid]: https://mermaidjs.github.io/ "Mermaid website"
906
[rouge]: http://rouge.jneen.net/ "Rouge website"
907
[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website"
908 909
[katex]: https://github.com/Khan/KaTeX "KaTeX website"
[katex-subset]: https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX "Macros supported by KaTeX"
910
[asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual"