BigW Consortium Gitlab

markdown.md.erb 8.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
# GitLab Markdown

This document is intended to be a comprehensive example of custom GitLab
Markdown usage. It will be parsed and then tested for accuracy. Let's get
started.

## Markdown

GitLab uses [Redcarpet](http://git.io/ld_NVQ) to parse all Markdown into
HTML.

It has some special features. Let's try 'em out!

### No Intra Emphasis

This string should have no emphasis: foo_bar_baz

### Tables

| Header   | Row  | Example |
| :------: | ---: | :------ |
| Foo      | Bar  | **Baz** |

### Fenced Code Blocks

```c
#include<stdio.h>

main()
{
    printf("Hello World");

}
```

```python
print "Hello, World!"
```

### Strikethrough

This text says this, ~~and this text doesn't~~.

### Superscript

This is my 1^(st) time using superscript in Markdown. Now this is my
2^(nd).

### Next step

After the Markdown has been turned into HTML, it gets passed through...

## HTML::Pipeline

### SanitizationFilter

57
GitLab uses <a href="http://git.io/vfW8a">HTML::Pipeline::SanitizationFilter</a>
58 59 60 61
to sanitize the generated HTML, stripping dangerous or unwanted tags.

Its default whitelist is pretty permissive. Check it:

62
<b>b tag</b> and <em>em tag</em>.
63

64
<code>code tag</code>
65 66 67

Press <kbd>s</kbd> to search.

68
<strike>Emoji</strike> Plain old images! <img src="http://www.emoji-cheat-sheet.com/graphics/emojis/smile.png" width="20" height="20" />
69 70 71

Here comes a line break:

72
<br />
73 74 75

And a horizontal rule:

76
<hr />
77 78 79

As permissive as it is, we've allowed even more stuff:

80
<span>span tag</span>
81

82 83 84 85 86
<details>
<summary>Summary lines are collapsible:</summary>
Hiding the details until expanded.
</details>

87
<a href="#" rel="bookmark">This is a link with a defined rel attribute, which should be removed</a>
88

89
<a href="javascript:alert('Hi')">This is a link trying to be sneaky. It gets its link removed entirely.</a>
90 91 92 93 94 95 96 97 98 99

### Escaping

The problem with SanitizationFilter is that it can be too aggressive.

| Input       | Expected         | Actual    |
| ----------- | ---------------- | --------- |
| `1 < 3 & 5` | 1 &lt; 3 &amp; 5 | 1 < 3 & 5 |
| `<foo>`     | &lt;foo&gt;      | <foo>     |

100 101 102 103 104 105 106 107
### Edge Cases

Markdown should be usable inside a link. Let's try!

- [_text_](#link-emphasis)
- [**text**](#link-strong)
- [`text`](#link-code)

108 109 110 111 112 113 114
### RelativeLinkFilter

Linking to a file relative to this project's repository should work.

[Relative Link](doc/README.md)
![Relative Image](app/assets/images/touch-icon-ipad.png)

115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
### EmojiFilter

Because life would be :zzz: without Emoji, right? :rocket:

Get ready for the Emoji :bomb:: :+1::-1::ok_hand::wave::v::raised_hand::muscle:

### TableOfContentsFilter

All headers in this document should be linkable. Try it.

### AutolinkFilter

These are all plain text that should get turned into links:

- http://about.gitlab.com/
- https://google.com/
- ftp://ftp.us.debian.org/debian/
- smb://foo/bar/baz
- irc://irc.freenode.net/git
- http://localhost:3000

But it shouldn't autolink text inside certain tags:

138 139 140
- <code>http://code.gitlab.com/</code>
- <a>http://a.gitlab.com/</a>
- <kbd>http://kbd.gitlab.com/</kbd>
141

142 143
### ExternalLinkFilter

144
External links get a `rel="nofollow noreferrer"` and `target="_blank"` attributes:
145 146 147 148

- [Google](https://google.com/)
- [GitLab Root](<%= Gitlab.config.gitlab.url %>)

149
### Reference Filters (e.g., <%= issue.to_reference %>)
150

151
References should be parseable even inside _<%= merge_request.to_reference %>_ emphasis.
152 153 154 155

#### UserReferenceFilter

- All: @all
156 157 158 159 160
- User: <%= user.to_reference %>
- Group: <%= group.to_reference %>
- Ignores invalid: <%= User.reference_prefix %>fake_user
- Ignored in code: `<%= user.to_reference %>`
- Ignored in links: [Link to <%= user.to_reference %>](#user-link)
161
- Link to user by reference: [User](<%= user.to_reference %>)
162 163 164

#### IssueReferenceFilter

165 166 167 168
- Issue: <%= issue.to_reference %>
- Issue in another project: <%= xissue.to_reference(project) %>
- Ignored in code: `<%= issue.to_reference %>`
- Ignored in links: [Link to <%= issue.to_reference %>](#issue-link)
Douwe Maan committed
169
- Issue by URL: <%= urls.namespace_project_issue_url(issue.project.namespace, issue.project, issue) %>
170
- Link to issue by reference: [Issue](<%= issue.to_reference %>)
Douwe Maan committed
171
- Link to issue by URL: [Issue](<%= urls.namespace_project_issue_url(issue.project.namespace, issue.project, issue) %>)
172 173 174

#### MergeRequestReferenceFilter

175 176 177 178
- Merge request: <%= merge_request.to_reference %>
- Merge request in another project: <%= xmerge_request.to_reference(project) %>
- Ignored in code: `<%= merge_request.to_reference %>`
- Ignored in links: [Link to <%= merge_request.to_reference %>](#merge-request-link)
Douwe Maan committed
179
- Merge request by URL: <%= urls.namespace_project_merge_request_url(merge_request.project.namespace, merge_request.project, merge_request) %>
180
- Link to merge request by reference: [Merge request](<%= merge_request.to_reference %>)
Douwe Maan committed
181
- Link to merge request by URL: [Merge request](<%= urls.namespace_project_merge_request_url(merge_request.project.namespace, merge_request.project, merge_request) %>)
182 183 184

#### SnippetReferenceFilter

185 186 187 188
- Snippet: <%= snippet.to_reference %>
- Snippet in another project: <%= xsnippet.to_reference(project) %>
- Ignored in code: `<%= snippet.to_reference %>`
- Ignored in links: [Link to <%= snippet.to_reference %>](#snippet-link)
Douwe Maan committed
189
- Snippet by URL: <%= urls.namespace_project_snippet_url(snippet.project.namespace, snippet.project, snippet) %>
190
- Link to snippet by reference: [Snippet](<%= snippet.to_reference %>)
Douwe Maan committed
191
- Link to snippet by URL: [Snippet](<%= urls.namespace_project_snippet_url(snippet.project.namespace, snippet.project, snippet) %>)
192 193 194

#### CommitRangeReferenceFilter

195 196 197 198
- Range: <%= commit_range.to_reference %>
- Range in another project: <%= xcommit_range.to_reference(project) %>
- Ignored in code: `<%= commit_range.to_reference %>`
- Ignored in links: [Link to <%= commit_range.to_reference %>](#commit-range-link)
Douwe Maan committed
199
- Range by URL: <%= urls.namespace_project_compare_url(commit_range.project.namespace, commit_range.project, commit_range.to_param) %>
200
- Link to range by reference: [Range](<%= commit_range.to_reference %>)
Douwe Maan committed
201
- Link to range by URL: [Range](<%= urls.namespace_project_compare_url(commit_range.project.namespace, commit_range.project, commit_range.to_param) %>)
202 203 204

#### CommitReferenceFilter

205 206 207 208
- Commit: <%= commit.to_reference %>
- Commit in another project: <%= xcommit.to_reference(project) %>
- Ignored in code: `<%= commit.to_reference %>`
- Ignored in links: [Link to <%= commit.to_reference %>](#commit-link)
Douwe Maan committed
209
- Commit by URL: <%= urls.namespace_project_commit_url(commit.project.namespace, commit.project, commit) %>
210
- Link to commit by reference: [Commit](<%= commit.to_reference %>)
Douwe Maan committed
211
- Link to commit by URL: [Commit](<%= urls.namespace_project_commit_url(commit.project.namespace, commit.project, commit) %>)
212 213 214

#### LabelReferenceFilter

215 216
- Label by ID: <%= simple_label.to_reference %>
- Label by name: <%= Label.reference_prefix %><%= simple_label.name %>
217
- Label by name in quotes: <%= label.to_reference(format: :name) %>
218 219
- Ignored in code: `<%= simple_label.to_reference %>`
- Ignored in links: [Link to <%= simple_label.to_reference %>](#label-link)
220
- Link to label by reference: [Label](<%= label.to_reference %>)
221

222 223
#### MilestoneReferenceFilter

224 225 226
- Milestone by ID: <%= simple_milestone.to_reference %>
- Milestone by name: <%= Milestone.reference_prefix %><%= simple_milestone.name %>
- Milestone by name in quotes: <%= milestone.to_reference(format: :name) %>
227
- Milestone in another project: <%= xmilestone.to_reference(project) %>
228 229
- Ignored in code: `<%= simple_milestone.to_reference %>`
- Ignored in links: [Link to <%= simple_milestone.to_reference %>](#milestone-link)
230
- Milestone by URL: <%= urls.namespace_project_milestone_url(milestone.project.namespace, milestone.project, milestone) %>
231
- Link to milestone by URL: [Milestone](<%= milestone.to_reference %>)
232

233 234 235 236 237 238 239 240 241
### Task Lists

- [ ] Incomplete task 1
- [x] Complete task 1
- [ ] Incomplete task 2
  - [ ] Incomplete sub-task 1
  - [ ] Incomplete sub-task 2
  - [x] Complete sub-task 1
- [X] Complete task 2
242 243 244 245 246 247 248 249 250

#### Gollum Tags

- [[linked-resource]]
- [[link-text|linked-resource]]
- [[http://example.com]]
- [[link-text|http://example.com/pdfs/gollum.pdf]]
- [[images/example.jpg]]
- [[http://example.com/images/example.jpg]]
251 252 253 254 255 256 257 258 259 260 261 262 263

### Inline Diffs

With inline diffs tags you can display {+ additions +} or [- deletions -].

The wrapping tags can be either curly braces or square brackets [+ additions +] or {- deletions -}.

However the wrapping tags can not be mixed as such -

- {+ additions +]
- [+ additions +}
- {- delletions -]
- [- delletions -}
264 265 266 267

### Videos

![My Video](/assets/videos/gitlab-demo.mp4)