You can also use other rich text files in GitLab. You might have to install a
dependency to do so. Please see the github-markup gem readme for more information.

Notes:

For the best result, we encourage you to check this document out as rendered
by GitLab itself: markdown.md

As of 11.1, GitLab uses the CommonMark Ruby Library for Markdown
processing of all new issues, merge requests, comments, and other Markdown content
in the GitLab system. As of 11.3, wiki pages and Markdown files (.md) in the
repositories are also processed with CommonMark. Older content in issues/comments
are still processed using the Redcarpet Ruby library.

Where there are significant differences, we will try to call them out in this document.

Transitioning to CommonMark

You may have Markdown documents in your repository that were written using some
of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a
slightly stricter syntax, these documents may now display a little strangely
since we've transitioned to CommonMark. Numbered lists with nested lists in
particular can be displayed incorrectly.

It is usually quite easy to fix. In the case of a nested list such as this:

1. Chocolate - dark - milk

simply add a space to each nested item:

1. Chocolate - dark - milk

In the documentation below, we try to highlight some of the differences.

If you have a need to view a document using RedCarpet, you can add the token
legacy_render=1 to the end of the url, like this:

If you have a large volume of Markdown files, it can be tedious to determine
if they will be displayed correctly or not. You can use the
diff_redcarpet_cmark
tool (not an officially supported product) to generate a list of files and
differences between how RedCarpet and CommonMark render the files. It can give
you a great idea if anything needs to be changed - many times nothing will need
to changed.

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:

Emoji

Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you::zap: You can use emoji anywhere GFM is supported. :v:You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support.On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support.Ubuntu 18.04 (like many modern Linux distros) has this font installed by default.

Sometimes you want to around a bit and add some to your . Well we have a gift for you:

You can use emoji anywhere GFM is supported.

You can use it to point out a or warn about patches. And if someone improves your really code, send them some . People will you for that.

If you are new to this, don't be . You can easily join the emoji . All you need to do is to look up one of the supported codes.

Standard Markdown

Headers

Header IDs and links

All Markdown-rendered headers automatically get IDs, except in comments.

On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else.

The IDs are generated from the content of the header according to the following rules:

All text is converted to lowercase.

All non-word text (e.g., punctuation, HTML) is removed.

All spaces are converted to hyphens.

Two or more hyphens in a row are converted to one.

If a header with the same ID has already been generated, a unique
incrementing number is appended, starting at 1.

For example:

# This header has spaces in it## This header has a :thumbsup: in it# This header has Unicode in it: 한글## This header has spaces in it### This header has spaces in it## This header has 3.5 in it (and parentheses)

Would generate the following link IDs:

this-header-has-spaces-in-it

this-header-has-a-in-it

this-header-has-unicode-in-it-한글

this-header-has-spaces-in-it

this-header-has-spaces-in-it-1

this-header-has-3-5-in-it-and-parentheses

Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID.

Lists

Examples:

1. First ordered list item2. Another item * Unordered sub-list.1. Actual numbers don't matter, just that it's a number 1. Ordered sub-list4. And another item.* Unordered list can use asterisks- Or minuses+ Or pluses

Becomes:

First ordered list item

Another item

Unordered sub-list.

Actual numbers don't matter, just that it's a number

Ordered sub-list

And another item.

Unordered list can use asterisks

Or minuses

Or pluses

If a list item contains multiple paragraphs,
each subsequent paragraph should be indented to the same level as the start of the list item text (Redcarpet: paragraph should be indented with four spaces.)

Example:

1. First ordered list item Second paragraph of first item.2. Another item

Becomes:

First ordered list item

Paragraph of first item.

Another item

If the paragraph of the first item is not indented with the proper number of spaces,
the paragraph will appear outside the list, instead of properly indented under the list item.

Example:

1. First ordered list item Paragraph of first item.2. Another item

Becomes:

First ordered list item

Paragraph of first item.

Another item

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](LICENSE)[I am an absolute reference within the repository](/doc/user/markdown.md)[I link to the Milestones page](/../milestones)[You can use numbers for reference-style link definitions][1]Or leave it empty and use the [link text itself][]Some text to show that the reference links can follow later.[arbitrary case-insensitive reference text]: https://www.mozilla.org[1]: http://slashdot.org[link text itself]: https://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

Examples:

Here's our logo (hover to see the title text):Inline-style:![alt text](img/markdown_logo.png)Reference-style:![alt text1][logo][logo]: img/markdown_logo.png

Becomes:

Here's our logo:

Inline-style:

Reference-style:

Blockquotes

Examples:

> Blockquotes are very handy in email to emulate reply text.> This line is part of the same quote.Quote break.> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote.

Becomes:

Blockquotes are very handy in email to emulate reply text.
This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can putMarkdown into a blockquote.

Inline HTML

You can also use raw HTML in your Markdown, and it'll mostly work pretty well.

See the documentation for HTML::Pipeline's SanitizationFilter class for the list of allowed HTML tags and attributes. In addition to the default SanitizationFilter whitelist, GitLab allows span, abbr, details and summary elements.

Details and Summary

Content can be collapsed using HTML's <details> and <summary> tags. This is especially useful for collapsing long logs so they take up less screen space.

Click me to collapse/fold.

These details will remain hidden until expanded.

PASTE LOGS HERE

Note: Markdown inside these tags is supported, as long as you have a blank line after the </summary> tag and before the </details> tag, as shown in the example. Redcarpet does not support Markdown inside these tags. You can work around this by using HTML, for example you can use <pre><code> tags instead of code fences.

Horizontal Rule

Examples:

Three or more...---Hyphens***Asterisks___Underscores

Becomes:

Three or more...

Hyphens

Asterisks

Underscores

Line Breaks

A good way to learn how line breaks work is to experiment and discover -- hit Enter once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. The "Preview" tab is your friend.

Here are some things to try out:

Examples:

Here's a line for us to start with.This line is separated from the one above by two newlines, so it will be a *separate paragraph*.This line is also a separate paragraph, but...This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*.This line is also a separate paragraph, and... This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*)spaces.

Becomes:

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it does not break and just follows the previous line in the same paragraph.

This line is also a separate paragraph, and...
This line is on its own line, because the previous line ends with two spaces. (but still in the same paragraph)

spaces.

Tables

Tables aren't part of the core Markdown spec, but they are part of GFM.