A 5-minute Markdown tutorial

At GitLab, we love Markdown for providing a simple, clean way to add styling and formatting to plain text, that's visible and repeatable across multiple applications. This means you can copy and paste the text without losing the formatting, and it makes reviewing diffs easier, as you're still reviewing plain text with no hidden data.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Markdown lets you add formatting elements to plaintext text documents. Since its creation, markdown has become one of the world’s most popular markup languages. There are many web-based applications specifically built for writing in Markdown. Markdown syntax is designed to be readable and simple.

Markdown tutorial

GitLab Product Marketing Manager William Chia recorded this five-minute Markdown tutorial for another GitLab team-member, so you can see how Markdown works within GitLab:

GitLab Flavored Markdown

GitLab uses GitLab Flavored Markdown (GFM) for other handy functionality not supported by standard Markdown. Here are a few useful things you can do with GFM:

Reference issues, commits, merge requests, or team members

When you type #12 (or any number) in an issue, it will automatically create a link to the corresponding issue in that project. You can also easily reference other GitLab-specific items.

Autolink URLs

You don't have to use the standard []() format to create a link: just pasting the URL will autolink it.

Create diagrams and flowcharts

In GitLab 10.3 we added the ability to generate diagrams and flowcharts using mermaid.

Quick actions

Open or close issues, reassign merge requests, add todos, unsubscribe from issues – these are just a few things you can do with GFM quick actions, all without leaving your keyboard. Just type / and a list of options will appear.

These are just a few examples of GFM – see the Markdown documentation for a full list. We're adding to it all the time: as of our last release you can quickly make an issue confidential right from the issue comment field. This was a community contribution, and we invite you to contribute functionality and quick actions you'd find useful too!

Benefits of using Markdown

Some may be skeptical of using Markdown when there are other options – like a WYSIWYG editor. But the benefits of using markdown are hard to ignore:

• Markdown is crazy versatile. It can be used for everything including (but not limited to) websites, notes, presentations, emails, and documents of all kinds.
• Markdown isn’t picky about its operating system. You can create Markdown-formatted text on any device running any operating system.
• Markdown can be used on the move, so to speak. Markdown-formatted text can be opened using virtually any application. You can also import your Markdown files into another Markdown application if you decide to make a change.
• The Markdown text you create won’t become obsolete. Even if the application you’re using stops working down the line, you’ll still be able to read your Markdown-formatted text using a text editing application. The fact that it is the backbone of so much web content means that you might be the odd one out if you DON’T use it.

How to get started with Markdown

There are a few ways you can learn about how to get started with Markdown.

The first is to check out online tutorials. You can find a number of resources on Markdown, including the original guide by John Gruber and a Markdown Tutorial open-source website that you can use to try out Markdown in your web browser.

Or, just try it out with the Notepad application on a device. Since Markdown is just plain text, you can write it in any text editor, such as Notepad. Save a file with the .MD file extension to make a proper Markdown file.

The second (and a highly encouraged) way to get the hang of Markdown is to check out some free online Markdown editors to test the waters - many of which are great for just learning how to write in Markdown. Markdown editors like StackEdit and Dillinger can help your efforts to get started with Markdown.

For the most optimal Markdown experience, a writing app that's built for Markdown is typically the best way to go.