# 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 GitLab uses <a href="http://git.io/vfW8a">HTML::Pipeline::SanitizationFilter</a> to sanitize the generated HTML, stripping dangerous or unwanted tags. Its default whitelist is pretty permissive. Check it: <b>b tag</b> and <em>em tag</em>. <code>code tag</code> Press <kbd>s</kbd> to search. <strike>Emoji</strike> Plain old images! <img src="http://www.emoji-cheat-sheet.com/graphics/emojis/smile.png" width="20" height="20" /> Here comes a line break: <br /> And a horizontal rule: <hr /> As permissive as it is, we've allowed even more stuff: <span>span tag</span> <a href="#" rel="bookmark">This is a link with a defined rel attribute, which should be removed</a> <a href="javascript:alert('Hi')">This is a link trying to be sneaky. It gets its link removed entirely.</a> ### 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> | ### Edge Cases Markdown should be usable inside a link. Let's try! - [_text_](#link-emphasis) - [**text**](#link-strong) - [`text`](#link-code) ### 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) ### 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: - <code>http://code.gitlab.com/</code> - <a>http://a.gitlab.com/</a> - <kbd>http://kbd.gitlab.com/</kbd> ### ExternalLinkFilter External links get a `rel="nofollow"` attribute: - [Google](https://google.com/) - [GitLab Root](<%= Gitlab.config.gitlab.url %>) ### Reference Filters (e.g., <%= issue.to_reference %>) References should be parseable even inside _<%= merge_request.to_reference %>_ emphasis. #### UserReferenceFilter - All: @all - 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) - Link to user by reference: [User](<%= user.to_reference %>) #### IssueReferenceFilter - 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) - Issue by URL: <%= urls.namespace_project_issue_url(issue.project.namespace, issue.project, issue) %> - Link to issue by reference: [Issue](<%= issue.to_reference %>) - Link to issue by URL: [Issue](<%= urls.namespace_project_issue_url(issue.project.namespace, issue.project, issue) %>) #### MergeRequestReferenceFilter - 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) - Merge request by URL: <%= urls.namespace_project_merge_request_url(merge_request.project.namespace, merge_request.project, merge_request) %> - Link to merge request by reference: [Merge request](<%= merge_request.to_reference %>) - Link to merge request by URL: [Merge request](<%= urls.namespace_project_merge_request_url(merge_request.project.namespace, merge_request.project, merge_request) %>) #### SnippetReferenceFilter - 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) - Snippet by URL: <%= urls.namespace_project_snippet_url(snippet.project.namespace, snippet.project, snippet) %> - Link to snippet by reference: [Snippet](<%= snippet.to_reference %>) - Link to snippet by URL: [Snippet](<%= urls.namespace_project_snippet_url(snippet.project.namespace, snippet.project, snippet) %>) #### CommitRangeReferenceFilter - 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) - Range by URL: <%= urls.namespace_project_compare_url(commit_range.project.namespace, commit_range.project, commit_range.to_param) %> - Link to range by reference: [Range](<%= commit_range.to_reference %>) - Link to range by URL: [Range](<%= urls.namespace_project_compare_url(commit_range.project.namespace, commit_range.project, commit_range.to_param) %>) #### CommitReferenceFilter - 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) - Commit by URL: <%= urls.namespace_project_commit_url(commit.project.namespace, commit.project, commit) %> - Link to commit by reference: [Commit](<%= commit.to_reference %>) - Link to commit by URL: [Commit](<%= urls.namespace_project_commit_url(commit.project.namespace, commit.project, commit) %>) #### LabelReferenceFilter - Label by ID: <%= simple_label.to_reference %> - Label by name: <%= Label.reference_prefix %><%= simple_label.name %> - Label by name in quotes: <%= label.to_reference(:name) %> - Ignored in code: `<%= simple_label.to_reference %>` - Ignored in links: [Link to <%= simple_label.to_reference %>](#label-link) - Link to label by reference: [Label](<%= label.to_reference %>) #### MilestoneReferenceFilter - Milestone: <%= milestone.to_reference %> - Milestone in another project: <%= xmilestone.to_reference(project) %> - Ignored in code: `<%= milestone.to_reference %>` - Link to milestone by URL: [Milestone](<%= urls.namespace_project_milestone_url(milestone.project.namespace, milestone.project, milestone) %>) ### 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 #### 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]]