Update markdown documentation, fix wiki spec.
This commit is contained in:
Marin Jankovski
parent
3f818a3d58
commit
656d9548bc
|
|
@ -8,23 +8,38 @@ Table of Contents
|
|||
**[GitLab Flavored Markdown](#gitlab-flavored-markdown-gfm)**
|
||||
|
||||
[Newlines](#newlines)
|
||||
|
||||
[Multiple underscores in words](#multiple-underscores-in-words)
|
||||
|
||||
[URL autolinking](#url-autolinking)
|
||||
|
||||
[Code and Syntax Highlighting](#code-and-syntax-highlighting)
|
||||
|
||||
[Emoji](#emoji)
|
||||
|
||||
[Special GitLab references](#special-gitlab-references)
|
||||
|
||||
|
||||
**[Standard Markdown](#standard-markdown)**
|
||||
|
||||
[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)
|
||||
|
||||
**[References](#references)**
|
||||
|
|
@ -33,7 +48,8 @@ Table of Contents
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -51,16 +67,20 @@ Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#mar
|
|||
|
||||
Newlines
|
||||
--------
|
||||
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.
|
||||
GFM honors the markdown specification in how [paragraphs and line breaks are handled](http://daringfireball.net/projects/markdown/syntax#p).
|
||||
|
||||
The next paragraph contains two phrases separated by a single newline character:
|
||||
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines.:
|
||||
|
||||
Roses are red
|
||||
Violets are blue
|
||||
|
||||
Sugar is sweet
|
||||
|
||||
Roses are red
|
||||
Violets are blue
|
||||
|
||||
Sugar is sweet
|
||||
|
||||
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.
|
||||
|
|
@ -319,13 +339,13 @@ Strikethrough uses two tildes. ~~Scratch this.~~
|
|||
|
||||
## Links
|
||||
|
||||
There are two ways to create links.
|
||||
There are two ways to create links, inline-style and reference-style.
|
||||
|
||||
[I'm an inline-style link](https://www.google.com)
|
||||
|
||||
[I'm a reference-style link][Arbitrary case-insensitive reference text]
|
||||
|
||||
[I'm a relative reference to a repository file](../blob/master/LICENSE)
|
||||
[I'm a relative reference to a repository file](LICENSE)
|
||||
|
||||
[You can use numbers for reference-style link definitions][1]
|
||||
|
||||
|
|
@ -341,7 +361,7 @@ There are two ways to create links.
|
|||
|
||||
[I'm a reference-style link][Arbitrary case-insensitive reference text]
|
||||
|
||||
[I'm a relative reference to a repository file](../blob/master/LICENSE)
|
||||
[I'm a relative reference to a repository file](LICENSE)
|
||||
|
||||
[You can use numbers for reference-style link definitions][1]
|
||||
|
||||
|
|
@ -353,6 +373,15 @@ Some text to show that the reference links can follow later.
|
|||
[1]: http://slashdot.org
|
||||
[link text itself]: http://www.reddit.com
|
||||
|
||||
**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]`
|
||||
|
||||
will point the link to `wikis/style` when the link is inside of a wiki markdown file.
|
||||
|
||||
## Images
|
||||
|
||||
Here's our logo (hover to see the title text):
|
||||
|
|
@ -365,15 +394,15 @@ Some text to show that the reference links can follow later.
|
|||
|
||||
[logo]: assets/logo-white.png
|
||||
|
||||
Here's our logo (hover to see the title text):
|
||||
Here's our logo:
|
||||
|
||||
Inline-style:
|
||||
|
||||
|
||||
|
||||
Reference-style:
|
||||
![alt text][logo]
|
||||
|
||||
[logo]: /assets/logo-white.png "Logo Title Text 2"
|
||||
[logo]: /assets/logo-white.png
|
||||
|
||||
## Blockquotes
|
||||
|
||||
|
|
|
|||
|
|
@ -440,12 +440,6 @@ describe GitlabMarkdownHelper do
|
|||
markdown(actual).should match(expected)
|
||||
end
|
||||
|
||||
it "should handle wiki urls" do
|
||||
actual = "[Link](test/link)\n"
|
||||
expected = "<p><a href=\"/#{project.path_with_namespace}/wikis/test/link\">Link</a></p>\n"
|
||||
markdown(actual).should match(expected)
|
||||
end
|
||||
|
||||
it "should handle relative urls in reference links for a file in master" do
|
||||
actual = "[GitLab API doc][GitLab readme]\n [GitLab readme]: doc/api/README.md\n"
|
||||
expected = "<p><a href=\"/#{project.path_with_namespace}/blob/master/doc/api/README.md\">GitLab API doc</a></p>\n"
|
||||
|
|
|
|||
Loading…
Reference in New Issue