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 2 %h3.page_title GitLab Flavored Markdown
3 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 @@
  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.
... ...