diff options
Diffstat (limited to 'doc/markdown/markdown.md')
| -rw-r--r-- | doc/markdown/markdown.md | 95 |
1 files changed, 40 insertions, 55 deletions
diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md index 47cb04cdb04..0d0a08d50d6 100644 --- a/doc/markdown/markdown.md +++ b/doc/markdown/markdown.md @@ -1,11 +1,6 @@ # Markdown ----------------------------------------------- - -Table of Contents -================= - ----------------------------------------------- +## Table of Contents **[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)** @@ -21,7 +16,6 @@ Table of Contents [Special GitLab references](#special-gitlab-references) - **[Standard Markdown](#standard-markdown)** [Headers](#headers) @@ -46,29 +40,24 @@ Table of Contents **[References](#references)** ----------------------------------------------- +## GitLab Flavored Markdown (GFM) -GitLab Flavored Markdown (GFM) -============================== -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. +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. You can use GFM in -* commit messages -* comments -* wall posts -* issues -* merge requests -* milestones -* wiki pages +- commit messages +- comments +- wall posts +- issues +- merge requests +- milestones +- wiki pages -You can also use other rich text files in GitLab. -You might have to install a depency to do so. -Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +You can also use other rich text files in GitLab. You might have to install a depency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. + +## Newlines -Newlines --------- GFM honors the markdown specification in how [paragraphs and line breaks are handled](http://daringfireball.net/projects/markdown/syntax#p). A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.: @@ -83,8 +72,8 @@ Violets are blue Sugar is sweet -Multiple underscores in words ------------------------------ +## Multiple underscores in words + 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 @@ -93,10 +82,9 @@ It is not reasonable to italicize just _part_ of a word, especially when you're perform_complicated_task do_this_and_do_that_and_another_thing -URL autolinking ---------------- -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. +## URL autolinking + +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. http://www.google.com @@ -164,8 +152,7 @@ s = "There is no highlighting for this." But let's throw in a <b>tag</b>. ``` -Emoji ------ +## Emoji Sometimes you want to be :cool: and add some :sparkles: to your :speech_balloon:. Well we have a :gift: for you: @@ -187,26 +174,25 @@ If you are :new: to this, don't be :fearful:. You can easily join the emoji :cir Consult the [Emoji Cheat Sheet](http://www.emoji-cheat-sheet.com/) for a list of all supported emoji codes. :thumbsup: -Special GitLab References ------ +## Special GitLab References GFM recognized special references. + You can easily reference e.g. a team member, an issue, or a commit within a project. + GFM will turn that reference into a link so you can navigate between them easily. GFM will recognize the following: -* @foo : for team members -* #123 : for issues -* !123 : for merge requests -* $123 : for snippets -* 1234567 : for commits -* \[file\](path/to/file) : for file references +- @foo : for team members +- #123 : for issues +- !123 : for merge requests +- $123 : for snippets +- 1234567 : for commits +- \[file\](path/to/file) : for file references ----------------------------------- # Standard Markdown ----------------------------------- ## Headers ```no-highlight @@ -249,12 +235,12 @@ On hover a link to those IDs becomes visible to make it easier to copy the link The IDs are generated from the content of the header according to the following rules: -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 +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 For example: @@ -377,8 +363,7 @@ Some text to show that the reference links can follow later. **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: +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]` @@ -399,9 +384,11 @@ will point the link to `wikis/style` when the link is inside of a wiki markdown Here's our logo: Inline-style: +  Reference-style: + ![alt text][logo] [logo]: /assets/logo-white.png @@ -518,10 +505,8 @@ Code above produces next output: | cell 1 | cell 2 | | cell 3 | cell 4 | ------------- - ## References -* 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. +- 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. |