Download as
Browse Code »

Commit 2a601d26f280f84beb0e109f84f346643f5734d6

Authored by Thurston Stone
Committed by Thurston Stone
1 parent 7ae72e65
Exists in master and in 4 other branches 6-8-stable, 7-0-stable, 7-0-stable-spb, spb-stable

Adding detailed documentation of the markdown syntax. 

This includes standard markdown as well as GitLab extended markdown as well as references to documents used.
Showing 2 changed files with 454 additions and 123 deletions   Show diff stats
app/views/help/markdown.html.haml
  Diff comments   View file @2a601d2
@@ -2,126 +2,6 @@ @@ -2,126 +2,6 @@
2 %h3.page_title GitLab Flavored Markdown 2 %h3.page_title GitLab Flavored Markdown
3 %br 3 %br
4 4
5 - .row  
6 - .span8  
7 - %p  
8 - For GitLab we developed something we call "GitLab Flavored Markdown" (GFM).  
9 - It extends the standard Markdown in a few significant ways adds some useful functionality.  
10 -  
11 - %p You can use GFM in:  
12 - %ul  
13 - %li commit messages  
14 - %li comments  
15 - %li wall posts  
16 - %li issues  
17 - %li merge requests  
18 - %li milestones  
19 - %li wiki pages  
20 -  
21 - .span4  
22 - .alert.alert-info  
23 - %p  
24 - If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent  
25 - %strong= link_to "Markdown Syntax Guide", "http://daringfireball.net/projects/markdown/syntax"  
26 - at Daring Fireball.  
27 -  
28 - .row  
29 - .span8  
30 - %h3 Differences from traditional Markdown  
31 -  
32 - %h4 Newlines  
33 -  
34 - %p  
35 - The biggest difference that GFM introduces is in the handling of linebreaks.  
36 - With traditional Markdown you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors.  
37 - GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.  
38 -  
39 -  
40 - %p The next paragraph contains two phrases separated by a single newline character:  
41 - %pre= "Roses are red\nViolets are blue"  
42 - %p becomes  
43 - = markdown "Roses are red\nViolets are blue"  
44 -  
45 - %h4 Multiple underscores in words  
46 -  
47 - %p  
48 - It is not reasonable to italicize just <em>part</em> of a word, especially when you're dealing with code and names often appear with multiple underscores.  
49 - Therefore, GFM ignores multiple underscores in words.  
50 -  
51 - %pre= "perform_complicated_task\ndo_this_and_do_that_and_another_thing"  
52 - %p becomes  
53 - = markdown "perform_complicated_task\ndo_this_and_do_that_and_another_thing"  
54 -  
55 - %h4 URL autolinking  
56 -  
57 - %p  
58 - GFM will autolink standard URLs you copy and paste into your text.  
59 - So if you want to link to a URL (instead of a textual link), you can simply put the URL in verbatim and it will be turned into a link to that URL.  
60 -  
61 - %h4 Fenced code blocks  
62 -  
63 - %p  
64 - Markdown converts text with four spaces at the front of each line to code blocks.  
65 - GFM supports that, but we also support fenced blocks.  
66 - Just wrap your code blocks in <code>```</code> and you won't need to indent manually to trigger a code block.  
67 -  
68 - %pre= %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}  
69 - %p becomes  
70 - = markdown %Q{```ruby\nrequire 'redcarpet'\nmarkdown = Redcarpet.new("Hello World!")\nputs markdown.to_html\n```}  
71 -  
72 - %h4 Emoji  
73 -  
74 - .row  
75 - .span8  
76 - :ruby  
77 - puts markdown %Q{Sometimes you want to be :cool: and add some :sparkles: to your :speech_balloon:. Well we have a :gift: for you:  
78 -  
79 - :exclamation: You can use emoji anywhere GFM is supported. :sunglasses:  
80 -  
81 - You can use it to point out a :bug: or warn about :monkey:patches. And if someone improves your really :snail: code, send them a :bouquet: or some :candy:. People will :heart: you for that.  
82 -  
83 - If you are :new: to this, don't be :fearful:. You can easily join the emoji :circus_tent:. All you need to do is to :book: up on the supported codes.  
84 - }  
85 -  
86 - .span4  
87 - .alert.alert-info  
88 - %p  
89 - Consult the  
90 - %strong= link_to "Emoji Cheat Sheet", "http://www.emoji-cheat-sheet.com/"  
91 - for a list of all supported emoji codes.  
92 -  
93 - .row  
94 - .span8  
95 - %h4 Special GitLab references  
96 -  
97 - %p  
98 - GFM recognizes special references.  
99 - You can easily reference e.g. a team member, an issue or a commit within a project.  
100 - GFM will turn that reference into a link so you can navigate between them easily.  
101 -  
102 - %p GFM will recognize the following references:  
103 - %ul  
104 - %li  
105 - %code @foo  
106 - for team members  
107 - %li  
108 - %code #123  
109 - for issues  
110 - %li  
111 - %code !123  
112 - for merge request  
113 - %li  
114 - %code $123  
115 - for snippets  
116 - %li  
117 - %code 1234567  
118 - for commits  
119 -  
120 - -# this example will only be shown if the user has a project with at least one issue  
121 - - if @project = current_user.authorized_projects.first  
122 - - if issue = @project.issues.first  
123 - %p For example in your #{link_to @project.name, project_path(@project)} project, writing:  
124 - %pre= "This is related to ##{issue.id}. @#{current_user.username} is working on solving it."  
125 - %p becomes:  
126 - = markdown "This is related to ##{issue.id}. @#{current_user.username} is working on solving it."  
127 - - @project = nil # Prevent this from bubbling up to page title 5 + .help_body
  6 + = preserve do
  7 + = markdown File.read(Rails.root.join("doc", "markdown", "markdown.md"))
doc/markdown/markdown.md 0 → 100644
  Diff comments   View file @2a601d2
@@ -0,0 +1,451 @@ @@ -0,0 +1,451 @@
  1 +
  2 +----------------------------------------------
  3 +
  4 +Table of Contents
  5 +=================
  6 +
  7 +----------------------------------------------
  8 +
  9 +[GitLab Flavored Markdown](#toc_3)
  10 +-------------------------------
  11 +[Newlines](#toc_4)
  12 +[Multiple underscores in words](#toc_5)
  13 +[URL autolinking](#toc_6)
  14 +[Code and Syntax Highlighting](#toc_7)
  15 +[Emoji](#toc_8)
  16 +[Special GitLab references](#toc_9)
  17 +
  18 +
  19 +
  20 +[Standard Markdown](#toc_10)
  21 +------------------------------
  22 +[Headers](#toc_11)
  23 +[Emphasis](#toc_20)
  24 +[Lists](#toc_21)
  25 +[Links](#toc_22)
  26 +[Images](#toc_23)
  27 +[Blockquotes](#toc_24)
  28 +[Inline HTML](#toc_25)
  29 +[Horizontal Rule](#toc_26)
  30 +[Line Breaks](#toc_27)
  31 +
  32 +[References](#toc_28)
  33 +---------------------
  34 +
  35 +----------------------------------------------
  36 +
  37 +<a name="gfm" />
  38 +GitLab Flavored Markdown (GFM)
  39 +==============================
  40 +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.
  41 +
  42 +You can use GFM in
  43 +
  44 +* commit messages
  45 +* comments
  46 +* wall posts
  47 +* issues
  48 +* merge requests
  49 +* milestones
  50 +* wiki pages
  51 +
  52 +<a name="newlines" />
  53 +Newlines
  54 +--------
  55 +The biggest difference that GFM introduces is in the handling of linebreaks. With traditional Markdown you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors. GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended.
  56 +
  57 +The next paragraph contains two phrases separated by a single newline character:
  58 +
  59 + Roses are red
  60 + Violets are blue
  61 +
  62 +Roses are red
  63 +Violets are blue
  64 +
  65 +<a name="underscores" />
  66 +Multiple underscores in words
  67 +-----------------------------
  68 +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.
  69 +
  70 + perform_complicated_task
  71 + do_this_and_do_that_and_another_thing
  72 +
  73 +perform_complicated_task
  74 +do_this_and_do_that_and_another_thing
  75 +
  76 +<a name="autolink" />
  77 +URL autolinking
  78 +---------------
  79 +GFM will autolink standard URLs you copy and paste into your text.
  80 +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.
  81 +
  82 + http://www.google.com
  83 +
  84 +http://www.google.com
  85 +
  86 +<a name="code"/>
  87 +## Code and Syntax Highlighting
  88 +
  89 +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.
  90 +
  91 +
  92 +```no-highlight
  93 +Inline `code` has `back-ticks around` it.
  94 +```
  95 +
  96 +Inline `code` has `back-ticks around` it.
  97 +
  98 +Example:
  99 +
  100 + ```javascript
  101 + var s = "JavaScript syntax highlighting";
  102 + alert(s);
  103 + ```
  104 +
  105 + ```python
  106 + def function():
  107 + #indenting works just fine in the fenced code block
  108 + s = "Python syntax highlighting"
  109 + print s
  110 + ```
  111 +
  112 + ```ruby
  113 + require 'redcarpet'
  114 + markdown = Redcarpet.new("Hello World!")
  115 + puts markdown.to_html
  116 + ```
  117 +
  118 + ```
  119 + No language indicated, so no syntax highlighting.
  120 + s = "There is no highlighting for this."
  121 + But let's throw in a <b>tag</b>.
  122 + ```
  123 +
  124 +becomes:
  125 +
  126 +```javascript
  127 +var s = "JavaScript syntax highlighting";
  128 +alert(s);
  129 +```
  130 +
  131 +```python
  132 +def function():
  133 + #indenting works just fine in the fenced code block
  134 + s = "Python syntax highlighting"
  135 + print s
  136 +```
  137 +
  138 +```ruby
  139 +require 'redcarpet'
  140 +markdown = Redcarpet.new("Hello World!")
  141 +puts markdown.to_html
  142 +```
  143 +
  144 +```
  145 +No language indicated, so no syntax highlighting.
  146 +s = "There is no highlighting for this."
  147 +But let's throw in a <b>tag</b>.
  148 +```
  149 +
  150 +<a name="emoji"/>
  151 +Emoji
  152 +-----
  153 +
  154 + Sometimes you want to be :cool: and add some :sparkles: to your :speech_balloon:. Well we have a :gift: for you:
  155 +
  156 + :exclamation: You can use emoji anywhere GFM is supported. :sunglasses:
  157 +
  158 + You can use it to point out a :bug: or warn about :monkey:patches. And if someone improves your really :snail: code, send them a :bouquet: or some :candy:. People will :heart: you for that.
  159 +
  160 + If you are :new: to this, don't be :fearful:. You can easily join the emoji :circus_tent:. All you need to do is to :book: up on the supported codes.
  161 +
  162 + Consult the [Emoji Cheat Sheet]( "http://www.emoji-cheat-sheet.com/") for a list of all supported emoji codes. :thumbsup:
  163 +
  164 +Sometimes you want to be :cool: and add some :sparkles: to your :speech_balloon:. Well we have a :gift: for you:
  165 +
  166 +:exclamation: You can use emoji anywhere GFM is supported. :sunglasses:
  167 +
  168 +You can use it to point out a :bug: or warn about :monkey:patches. And if someone improves your really :snail: code, send them a :bouquet: or some :candy:. People will :heart: you for that.
  169 +
  170 +If you are :new: to this, don't be :fearful:. You can easily join the emoji :circus_tent:. All you need to do is to :book: up on the supported codes.
  171 +
  172 +Consult the [Emoji Cheat Sheet]( "http://www.emoji-cheat-sheet.com/") for a list of all supported emoji codes. :thumbsup:
  173 +
  174 +<a name="special"/>
  175 +Special GitLab References
  176 +-----
  177 +
  178 +GFM recognized special references.
  179 +You can easily reference e.g. a team member, an issue, or a commit within a project.
  180 +GFM will turn that reference into a link so you can navigate between them easily.
  181 +
  182 +
  183 +GFM will recognize the following:
  184 +
  185 +* @foo : for team members
  186 +* #123 : for issues
  187 +* !123 : for merge requests
  188 +* $123 : for snippets
  189 +* 1234567 : for commits
  190 +* [file](path/to/file) : for file references
  191 +
  192 +<a name="standard"/>
  193 +
  194 +----------------------------------
  195 +# Standard Markdown
  196 +
  197 +----------------------------------
  198 +<a name="headers"/>
  199 +## Headers
  200 +
  201 +```no-highlight
  202 +# H1
  203 +## H2
  204 +### H3
  205 +#### H4
  206 +##### H5
  207 +###### H6
  208 +
  209 +Alternatively, for H1 and H2, an underline-ish style:
  210 +
  211 +Alt-H1
  212 +======
  213 +
  214 +Alt-H2
  215 +------
  216 +```
  217 +
  218 +# H1
  219 +## H2
  220 +### H3
  221 +#### H4
  222 +##### H5
  223 +###### H6
  224 +
  225 +Alternatively, for H1 and H2, an underline-ish style:
  226 +
  227 +Alt-H1
  228 +======
  229 +
  230 +Alt-H2
  231 +------
  232 +
  233 +<a name="emphasis"/>
  234 +## Emphasis
  235 +
  236 +```no-highlight
  237 +Emphasis, aka italics, with *asterisks* or _underscores_.
  238 +
  239 +Strong emphasis, aka bold, with **asterisks** or __underscores__.
  240 +
  241 +Combined emphasis with **asterisks and _underscores_**.
  242 +
  243 +Strikethrough uses two tildes. ~~Scratch this.~~
  244 +```
  245 +
  246 +Emphasis, aka italics, with *asterisks* or _underscores_.
  247 +
  248 +Strong emphasis, aka bold, with **asterisks** or __underscores__.
  249 +
  250 +Combined emphasis with **asterisks and _underscores_**.
  251 +
  252 +Strikethrough uses two tildes. ~~Scratch this.~~
  253 +
  254 +
  255 +<a name="lists"/>
  256 +## Lists
  257 +
  258 +```no-highlight
  259 +1. First ordered list item
  260 +2. Another item
  261 + * Unordered sub-list.
  262 +1. Actual numbers don't matter, just that it's a number
  263 + 1. Ordered sub-list
  264 +4. And another item.
  265 +
  266 + Some text that should be aligned with the above item.
  267 +
  268 +* Unordered list can use asterisks
  269 +- Or minuses
  270 ++ Or pluses
  271 +```
  272 +
  273 +1. First ordered list item
  274 +2. Another item
  275 + * Unordered sub-list.
  276 +1. Actual numbers don't matter, just that it's a number
  277 + 1. Ordered sub-list
  278 +4. And another item.
  279 +
  280 + Some text that should be aligned with the above item.
  281 +
  282 +* Unordered list can use asterisks
  283 +- Or minuses
  284 ++ Or pluses
  285 +
  286 +<a name="links"/>
  287 +## Links
  288 +
  289 +There are two ways to create links.
  290 +
  291 + [I'm an inline-style link](https://www.google.com)
  292 +
  293 + [I'm a reference-style link][Arbitrary case-insensitive reference text]
  294 +
  295 + [I'm a relative reference to a repository file](../blob/master/LICENSE)
  296 +
  297 + [You can use numbers for reference-style link definitions][1]
  298 +
  299 + Or leave it empty and use the [link text itself][]
  300 +
  301 + Some text to show that the reference links can follow later.
  302 +
  303 + [arbitrary case-insensitive reference text]: https://www.mozilla.org
  304 + [1]: http://slashdot.org
  305 + [link text itself]: http://www.reddit.com
  306 +
  307 +[I'm an inline-style link](https://www.google.com)
  308 +
  309 +[I'm a reference-style link][Arbitrary case-insensitive reference text]
  310 +
  311 +[I'm a relative reference to a repository file](../blob/master/LICENSE)
  312 +
  313 +[You can use numbers for reference-style link definitions][1]
  314 +
  315 +Or leave it empty and use the [link text itself][]
  316 +
  317 +Some text to show that the reference links can follow later.
  318 +
  319 +[arbitrary case-insensitive reference text]: https://www.mozilla.org
  320 +[1]: http://slashdot.org
  321 +[link text itself]: http://www.reddit.com
  322 +
  323 +<a name="images"/>
  324 +## Images
  325 +
  326 + Here's our logo (hover to see the title text):
  327 +
  328 + Inline-style:
  329 + ![alt text](/assets/logo-white.png "Logo Title Text 1")
  330 +
  331 + Reference-style:
  332 + ![alt text][logo]
  333 +
  334 + [logo]: /assets/logo-white.png "Logo Title Text 2"
  335 +
  336 +Here's our logo (hover to see the title text):
  337 +
  338 +Inline-style:
  339 +![alt text](/assets/logo-white.png "Logo Title Text 1")
  340 +
  341 +Reference-style:
  342 +![alt text][logo]
  343 +
  344 +[logo]: /assets/logo-white.png "Logo Title Text 2"
  345 +
  346 +<a name="blockquotes"/>
  347 +## Blockquotes
  348 +
  349 +```no-highlight
  350 +> Blockquotes are very handy in email to emulate reply text.
  351 +> This line is part of the same quote.
  352 +
  353 +Quote break.
  354 +
  355 +> 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.
  356 +```
  357 +
  358 +> Blockquotes are very handy in email to emulate reply text.
  359 +> This line is part of the same quote.
  360 +
  361 +Quote break.
  362 +
  363 +> 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.
  364 +
  365 +<a name="html"/>
  366 +## Inline HTML
  367 +
  368 +You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
  369 +
  370 +```no-highlight
  371 +<dl>
  372 + <dt>Definition list</dt>
  373 + <dd>Is something people use sometimes.</dd>
  374 +
  375 + <dt>Markdown in HTML</dt>
  376 + <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
  377 +</dl>
  378 +```
  379 +
  380 +<dl>
  381 + <dt>Definition list</dt>
  382 + <dd>Is something people use sometimes.</dd>
  383 +
  384 + <dt>Markdown in HTML</dt>
  385 + <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
  386 +</dl>
  387 +
  388 +<a name="hr"/>
  389 +## Horizontal Rule
  390 +
  391 +```
  392 +Three or more...
  393 +
  394 +---
  395 +
  396 +Hyphens
  397 +
  398 +***
  399 +
  400 +Asterisks
  401 +
  402 +___
  403 +
  404 +Underscores
  405 +```
  406 +
  407 +Three or more...
  408 +
  409 +---
  410 +
  411 +Hyphens
  412 +
  413 +***
  414 +
  415 +Asterisks
  416 +
  417 +___
  418 +
  419 +Underscores
  420 +
  421 +<a name="lines"/>
  422 +## Line Breaks
  423 +
  424 +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.
  425 +
  426 +Here are some things to try out:
  427 +
  428 +```
  429 +Here's a line for us to start with.
  430 +
  431 +This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
  432 +
  433 +This line is also a separate paragraph, but...
  434 +This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
  435 +```
  436 +
  437 +Here's a line for us to start with.
  438 +
  439 +This line is separated from the one above by two newlines, so it will be a *separate paragraph*.
  440 +
  441 +This line is also begins a separate paragraph, but...
  442 +This line is only separated by a single newline, so it's a separate line in the *same paragraph*.
  443 +
  444 +------------
  445 +
  446 +<a name="references"/>
  447 +## References
  448 +
  449 +* This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
  450 +* The [Markdown Syntax Guide](http://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown.
  451 +* [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown.