2015-04-23 04:21:11 +00:00
|
|
|
# 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
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
GitLab uses <a href="http://git.io/vfW8a">HTML::Pipeline::SanitizationFilter</a>
|
2015-04-23 04:21:11 +00:00
|
|
|
to sanitize the generated HTML, stripping dangerous or unwanted tags.
|
|
|
|
|
|
|
|
Its default whitelist is pretty permissive. Check it:
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<b>b tag</b> and <em>em tag</em>.
|
2015-04-23 04:21:11 +00:00
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<code>code tag</code>
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
Press <kbd>s</kbd> to search.
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<strike>Emoji</strike> Plain old images! <img src="http://www.emoji-cheat-sheet.com/graphics/emojis/smile.png" width="20" height="20" />
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
Here comes a line break:
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<br />
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
And a horizontal rule:
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<hr />
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
As permissive as it is, we've allowed even more stuff:
|
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<span>span tag</span>
|
2015-04-23 04:21:11 +00:00
|
|
|
|
2016-09-28 11:46:11 +00:00
|
|
|
<details>
|
|
|
|
<summary>Summary lines are collapsible:</summary>
|
|
|
|
Hiding the details until expanded.
|
|
|
|
</details>
|
|
|
|
|
2015-05-27 19:39:08 +00:00
|
|
|
<a href="#" rel="bookmark">This is a link with a defined rel attribute, which should be removed</a>
|
2015-04-23 04:21:11 +00:00
|
|
|
|
2015-05-08 16:17:54 +00:00
|
|
|
<a href="javascript:alert('Hi')">This is a link trying to be sneaky. It gets its link removed entirely.</a>
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
### Escaping
|
|
|
|
|
|
|
|
The problem with SanitizationFilter is that it can be too aggressive.
|
|
|
|
|
|
|
|
| Input | Expected | Actual |
|
|
|
|
| ----------- | ---------------- | --------- |
|
|
|
|
| `1 < 3 & 5` | 1 < 3 & 5 | 1 < 3 & 5 |
|
|
|
|
| `<foo>` | <foo> | <foo> |
|
|
|
|
|
2015-05-06 21:21:19 +00:00
|
|
|
### Edge Cases
|
|
|
|
|
|
|
|
Markdown should be usable inside a link. Let's try!
|
|
|
|
|
|
|
|
- [_text_](#link-emphasis)
|
|
|
|
- [**text**](#link-strong)
|
|
|
|
- [`text`](#link-code)
|
|
|
|
|
2015-07-23 01:22:16 +00:00
|
|
|
### 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)
|
|
|
|
|
2015-04-23 04:21:11 +00:00
|
|
|
### EmojiFilter
|
|
|
|
|
|
|
|
Because life would be :zzz: without Emoji, right? :rocket:
|
|
|
|
|
2017-04-25 10:06:24 +00:00
|
|
|
Get ready for the Emoji :bomb: : :+1: :-1: :ok_hand: :wave: :v: :raised_hand: :muscle:
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
### 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:
|
|
|
|
|
2015-07-21 04:21:51 +00:00
|
|
|
- <code>http://code.gitlab.com/</code>
|
|
|
|
- <a>http://a.gitlab.com/</a>
|
|
|
|
- <kbd>http://kbd.gitlab.com/</kbd>
|
2015-04-23 04:21:11 +00:00
|
|
|
|
2015-05-27 19:39:08 +00:00
|
|
|
### ExternalLinkFilter
|
|
|
|
|
2016-06-08 07:02:55 +00:00
|
|
|
External links get a `rel="nofollow noreferrer"` and `target="_blank"` attributes:
|
2015-05-27 19:39:08 +00:00
|
|
|
|
|
|
|
- [Google](https://google.com/)
|
|
|
|
- [GitLab Root](<%= Gitlab.config.gitlab.url %>)
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
### Reference Filters (e.g., <%= issue.to_reference %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
References should be parseable even inside _<%= merge_request.to_reference %>_ emphasis.
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### UserReferenceFilter
|
|
|
|
|
|
|
|
- All: @all
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to user by reference: [User](<%= user.to_reference %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### IssueReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Issue by URL: <%= urls.project_issue_url(issue.project, issue) %>
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to issue by reference: [Issue](<%= issue.to_reference %>)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Link to issue by URL: [Issue](<%= urls.project_issue_url(issue.project, issue) %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### MergeRequestReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Merge request by URL: <%= urls.project_merge_request_url(merge_request.project, merge_request) %>
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to merge request by reference: [Merge request](<%= merge_request.to_reference %>)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Link to merge request by URL: [Merge request](<%= urls.project_merge_request_url(merge_request.project, merge_request) %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### SnippetReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Snippet by URL: <%= urls.project_snippet_url(snippet.project, snippet) %>
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to snippet by reference: [Snippet](<%= snippet.to_reference %>)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Link to snippet by URL: [Snippet](<%= urls.project_snippet_url(snippet.project, snippet) %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### CommitRangeReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Range by URL: <%= urls.project_compare_url(commit_range.project, commit_range.to_param) %>
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to range by reference: [Range](<%= commit_range.to_reference %>)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Link to range by URL: [Range](<%= urls.project_compare_url(commit_range.project, commit_range.to_param) %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### CommitReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- 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)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Commit by URL: <%= urls.project_commit_url(commit.project, commit) %>
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to commit by reference: [Commit](<%= commit.to_reference %>)
|
2017-06-29 17:06:35 +00:00
|
|
|
- Link to commit by URL: [Commit](<%= urls.project_commit_url(commit.project, commit) %>)
|
2015-04-23 04:21:11 +00:00
|
|
|
|
|
|
|
#### LabelReferenceFilter
|
|
|
|
|
2015-05-03 03:59:55 +00:00
|
|
|
- Label by ID: <%= simple_label.to_reference %>
|
|
|
|
- Label by name: <%= Label.reference_prefix %><%= simple_label.name %>
|
2016-02-25 07:37:49 +00:00
|
|
|
- Label by name in quotes: <%= label.to_reference(format: :name) %>
|
2015-05-03 03:59:55 +00:00
|
|
|
- Ignored in code: `<%= simple_label.to_reference %>`
|
|
|
|
- Ignored in links: [Link to <%= simple_label.to_reference %>](#label-link)
|
2015-12-01 16:04:32 +00:00
|
|
|
- Link to label by reference: [Label](<%= label.to_reference %>)
|
2015-05-04 21:37:37 +00:00
|
|
|
|
2015-12-24 13:43:07 +00:00
|
|
|
#### MilestoneReferenceFilter
|
|
|
|
|
2016-03-31 02:12:34 +00:00
|
|
|
- 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) %>
|
2015-12-24 13:43:07 +00:00
|
|
|
- Milestone in another project: <%= xmilestone.to_reference(project) %>
|
2016-03-31 02:12:34 +00:00
|
|
|
- Ignored in code: `<%= simple_milestone.to_reference %>`
|
|
|
|
- Ignored in links: [Link to <%= simple_milestone.to_reference %>](#milestone-link)
|
2017-08-03 11:50:06 +00:00
|
|
|
- Milestone by URL: <%= urls.milestone_url(milestone) %>
|
2016-03-31 02:12:34 +00:00
|
|
|
- Link to milestone by URL: [Milestone](<%= milestone.to_reference %>)
|
2017-08-03 11:50:06 +00:00
|
|
|
- Group milestone by name: <%= Milestone.reference_prefix %><%= group_milestone.name %>
|
|
|
|
- Group milestone by name in quotes: <%= group_milestone.to_reference(format: :name) %>
|
|
|
|
- Group milestone by URL is ignore: <%= urls.milestone_url(group_milestone) %>
|
2015-12-24 13:43:07 +00:00
|
|
|
|
2015-05-04 21:37:37 +00:00
|
|
|
### 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
|
2016-01-12 21:00:35 +00:00
|
|
|
|
|
|
|
#### 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]]
|
2016-04-06 19:37:09 +00:00
|
|
|
|
|
|
|
### 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 -}.
|
|
|
|
|
2017-12-14 18:14:23 +00:00
|
|
|
Examples:
|
2016-04-06 19:37:09 +00:00
|
|
|
|
2017-12-14 18:14:23 +00:00
|
|
|
```
|
|
|
|
- {+ additions +}
|
|
|
|
- [+ additions +]
|
|
|
|
- {- deletions -}
|
|
|
|
- [- deletions -]
|
|
|
|
```
|
|
|
|
|
|
|
|
However the wrapping tags cannot be mixed as such:
|
|
|
|
|
|
|
|
```
|
2016-04-06 19:37:09 +00:00
|
|
|
- {+ additions +]
|
|
|
|
- [+ additions +}
|
2017-12-14 18:14:23 +00:00
|
|
|
- {- deletions -]
|
|
|
|
- [- deletions -}
|
|
|
|
```
|
2016-07-12 17:28:39 +00:00
|
|
|
|
|
|
|
### Videos
|
|
|
|
|
|
|
|
![My Video](/assets/videos/gitlab-demo.mp4)
|
2017-11-22 03:12:04 +00:00
|
|
|
|
2017-12-20 11:39:40 +00:00
|
|
|
### Colors
|
|
|
|
|
|
|
|
`#F00`
|
|
|
|
`#F00A`
|
|
|
|
`#FF0000`
|
|
|
|
`#FF0000AA`
|
|
|
|
`RGB(0,255,0)`
|
|
|
|
`RGB(0%,100%,0%)`
|
|
|
|
`RGBA(0,255,0,0.7)`
|
|
|
|
`HSL(540,70%,50%)`
|
|
|
|
`HSLA(540,70%,50%,0.7)`
|
|
|
|
|
2017-11-22 03:12:04 +00:00
|
|
|
### Mermaid
|
|
|
|
|
|
|
|
> If this is not rendered correctly, see
|
|
|
|
https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid
|
|
|
|
|
|
|
|
It is possible to generate diagrams and flowcharts from text using [Mermaid][mermaid].
|
|
|
|
|
|
|
|
In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block.
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
graph TD;
|
|
|
|
A-->B;
|
|
|
|
A-->C;
|
|
|
|
B-->D;
|
|
|
|
C-->D;
|
|
|
|
```
|
|
|
|
|
|
|
|
Becomes:
|
|
|
|
|
|
|
|
```mermaid
|
|
|
|
graph TD;
|
|
|
|
A-->B;
|
|
|
|
A-->C;
|
|
|
|
B-->D;
|
|
|
|
C-->D;
|
|
|
|
```
|
|
|
|
|
|
|
|
For details see the [Mermaid official page][mermaid].
|
|
|
|
|
|
|
|
[mermaid]: https://mermaidjs.github.io/ "Mermaid website"
|
|
|
|
|