markdown.md 13.4 KB
Newer Older
Marin Jankovski's avatar
Marin Jankovski committed
1 2
# Markdown

3
## Table of Contents
4

5 6
**[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)**

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
7 8
* [Newlines](#newlines)
* [Multiple underscores in words](#multiple-underscores-in-words)
9
* [URL auto-linking](#url-autolinking)
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
10 11 12
* [Code and Syntax Highlighting](#code-and-syntax-highlighting)
* [Emoji](#emoji)
* [Special GitLab references](#special-gitlab-references)
Vinnie Okada's avatar
Vinnie Okada committed
13
* [Task lists](#task-lists)
14 15 16

**[Standard Markdown](#standard-markdown)**

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
17 18 19 20 21 22 23 24 25 26
* [Headers](#headers)
* [Emphasis](#emphasis)
* [Lists](#lists)
* [Links](#links)
* [Images](#images)
* [Blockquotes](#blockquotes)
* [Inline HTML](#inline-html)
* [Horizontal Rule](#horizontal-rule)
* [Line Breaks](#line-breaks)
* [Tables](#tables)
27 28

**[References](#references)**
29

30
## GitLab Flavored Markdown (GFM)
31

32
For GitLab we developed something we call "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality.
33 34 35

You can use GFM in

36 37 38 39 40 41
- commit messages
- comments
- issues
- merge requests
- milestones
- wiki pages
42

43
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.
44 45

## Newlines
46

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

49
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.:
50 51 52 53

    Roses are red
    Violets are blue

54 55
    Sugar is sweet

56 57
Roses are red
Violets are blue
58

59 60
Sugar is sweet

61 62
## Multiple underscores in words

63 64 65 66 67 68 69 70
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.

    perform_complicated_task
    do_this_and_do_that_and_another_thing

perform_complicated_task
do_this_and_do_that_and_another_thing

71
## URL auto-linking
72 73

GFM will autolink standard URLs you copy and paste into your text. So if you want to link to a URL (instead of a textural link), you can simply put the URL in verbatim and it will be turned into a link to that URL.
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94

    http://www.google.com

http://www.google.com

## Code and Syntax Highlighting

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.

```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);
    ```
95

96 97 98 99 100 101
    ```python
    def function():
        #indenting works just fine in the fenced code block
        s = "Python syntax highlighting"
        print s
    ```
102

103 104 105 106 107 108 109
    ```ruby
    require 'redcarpet'
    markdown = Redcarpet.new("Hello World!")
    puts markdown.to_html
    ```

    ```
110
    No language indicated, so no syntax highlighting.
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
    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>.
```

141
## Emoji
142

Robert Schilling's avatar
Robert Schilling committed
143
	Sometimes you want to be a :ninja: and add some :glowing_star: to your :speech_balloon:. Well we have a gift for you:
144

Robert Schilling's avatar
Robert Schilling committed
145
	:high_voltage_sign: You can use emoji anywhere GFM is supported. :victory_hand:
146

Robert Schilling's avatar
Robert Schilling committed
147
	You can use it to point out a :bug: or warn about :speak_no_evil_monkey: patches. And if someone improves your really :snail: code, send them some :cake:. People will :heart: you for that.
148

Robert Schilling's avatar
Robert Schilling committed
149
	If you are new to this, don't be :fearful_face:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes.
150

Robert Schilling's avatar
Robert Schilling committed
151
	Consult the [Emoji Cheat Sheet](https://www.dropbox.com/s/b9xaqb977s6d8w1/cheat_sheet.pdf) for a list of all supported emoji codes. :thumbsup:
152

Robert Schilling's avatar
Robert Schilling committed
153
Sometimes you want to be a :ninja: and add some :glowing_star: to your :speech_balloon:. Well we have a gift for you:
154

Robert Schilling's avatar
Robert Schilling committed
155
:high_voltage_sign: You can use emoji anywhere GFM is supported. :victory_hand:
156

Robert Schilling's avatar
Robert Schilling committed
157
You can use it to point out a :bug: or warn about :speak_no_evil_monkey: patches. And if someone improves your really :snail: code, send them some :cake:. People will :heart: you for that.
158

Robert Schilling's avatar
Robert Schilling committed
159
If you are new to this, don't be :fearful_face:. You can easily join the emoji :family:. All you need to do is to look up on the supported codes.
160

Robert Schilling's avatar
Robert Schilling committed
161
Consult the [Emoji Cheat Sheet](https://www.dropbox.com/s/b9xaqb977s6d8w1/cheat_sheet.pdf) for a list of all supported emoji codes. :thumbsup:
162

163
## Special GitLab References
164 165

GFM recognized special references.
166

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

169 170 171 172
GFM will turn that reference into a link so you can navigate between them easily.

GFM will recognize the following:

173
- @foo : for team members
174
- @all : for the whole team
175 176 177 178 179
- #123 : for issues
- !123 : for merge requests
- $123 : for snippets
- 1234567 : for commits
- \[file\](path/to/file) : for file references
180

181 182 183 184 185 186
GFM also recognizes references to commits, issues, and merge requests in other projects:

- namespace/project#123 : for issues
- namespace/project!123 : for merge requests
- namespace/project@1234567 : for commits

Vinnie Okada's avatar
Vinnie Okada committed
187 188 189 190 191 192 193 194 195 196 197 198
## Task Lists

You can add task lists to merge request and issue descriptions to keep track of to-do items.  To create a task, add an unordered list to the description in an issue or merge request, formatted like so:

```no-highlight
* [x] Completed task
* [ ] Unfinished task
    * [x] Nested task
```

Task lists can only be created in descriptions, not in titles or comments.  Task item state can be managed by editing the description's Markdown or by clicking the rendered checkboxes.

199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
# Standard Markdown

## Headers

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

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

Alt-H1
======

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

# H1
## H2
### H3
#### H4
##### H5
###### H6

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

Alt-H1
======

Alt-H2
------

235 236 237 238 239 240 241 242
### Header IDs and links

All markdown rendered headers automatically get IDs, except for comments.

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:

243 244 245 246 247 248
1. remove the heading hashes `#` and process the rest of the line as it would be processed if it were not a header
2. from the result, remove all HTML tags, but keep their inner content
3. convert all characters to lowercase
4. convert all characters except `[a-z0-9_-]` into hyphens `-`
5. transform multiple adjacent hyphens into a single hyphen
6. remove trailing and heading hyphens
249 250 251 252

For example:

```
253
###### ..Ab_c-d. e [anchor](URL) ![alt text](URL)..
254 255 256 257
```

which renders as:

258
###### ..Ab_c-d. e [anchor](URL) ![alt text](URL)..
259 260 261 262

will first be converted by step 1) into a string like:

```
263
..Ab_c-d. e &lt;a href="URL">anchor&lt;/a> &lt;img src="URL" alt="alt text"/>..
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
```

After removing the tags in step 2) we get:

```
..Ab_c-d. e anchor ..
```

And applying all the other steps gives the id:

```
ab_c-d-e-anchor
```

Note in particular how:

280 281
- for markdown anchors `[text](URL)`, only the `text` is used
- markdown images `![alt](URL)` are completely ignored
282

283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
## Emphasis

```no-highlight
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.~~
```

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

## Lists

```no-highlight
1. First ordered list item
2. Another item
308
  * Unordered sub-list.
309 310
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
311 312
4. And another item.

313 314 315 316 317 318 319 320 321
   Some text that should be aligned with the above item.

* Unordered list can use asterisks
- Or minuses
+ Or pluses
```

1. First ordered list item
2. Another item
322
  * Unordered sub-list.
323 324
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
325 326
4. And another item.

327 328 329 330 331 332 333 334
   Some text that should be aligned with the above item.

* Unordered list can use asterisks
- Or minuses
+ Or pluses

## Links

335
There are two ways to create links, inline-style and reference-style.
336 337 338 339 340

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

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

341
    [I'm a relative reference to a repository file](LICENSE)
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356

    [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
    [link text itself]: http://www.reddit.com

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

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

357
[I'm a relative reference to a repository file](LICENSE)
358 359 360 361 362 363 364 365 366 367 368

[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
[link text itself]: http://www.reddit.com

369 370
**Note**

371
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:
372 373 374 375 376

`[I'm a reference-style link][style]`

will point the link to `wikis/style` when the link is inside of a wiki markdown file.

377 378 379 380
## Images

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

381
    Inline-style:
382
    ![alt text](assets/logo-white.png)
383

384
    Reference-style:
385
    ![alt text1][logo]
386

387
    [logo]: assets/logo-white.png
388

389
Here's our logo:
390

391
Inline-style:
392

393
![alt text](/assets/logo-white.png)
394

395
Reference-style:
396

397 398
![alt text][logo]

399
[logo]: /assets/logo-white.png
400 401 402 403 404 405 406 407 408

## Blockquotes

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

Quote break.

409
> 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.
410 411 412 413 414 415 416
```

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

Quote break.

417
> 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.
418 419 420

## Inline HTML

421
You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474

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

## Horizontal Rule

```
Three or more...

---

Hyphens

***

Asterisks

___

Underscores
```

Three or more...

---

Hyphens

***

Asterisks

___

Underscores

## Line Breaks

475
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.
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491

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...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
```

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

492
This line is also begins a separate paragraph, but...
493 494
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.

495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512
## Tables

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   |

513 514 515 516
**Note**

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

517 518
## References

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