A 5-minute Markdown tutorial

Rebecca Dodd ·
Aug 17, 2018 · 4 min read · Leave a comment

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.

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:

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.

“A 5-minute #markdown tutorial by @TheWilliamChia” – Rebecca Dodd

Click to tweet

Open in Web IDE View source