Five minutes to Markdown mastery

Markdown is a simple formatting language developed by John Gruber as a simpler way to create HTML documents. It's become a ubiquitous part of the web and all kinds of sites are using it. In fact you may be using Markdown on some of your favorite sites and not even realize it. Sites like GitHub and StackOverflow use it to format user generated input such as comments, and apps like Middlemand and Jeckyl use it as the primary publishing format. Here at Remarq we turn Markdown into super high quality PDF documents. If you're curious why it's become so popular Brett Terpstra has written a great two-minute explanation.

What follows is a quick explanaion of HOW the basics of Markdown work. We'll look at all of the core features that any Markdown service should support. In a follow up article we'll see some of the special extensions to Markdown that we use here at Remarq.

Normal text

Normal text is easy.

You just... type normal text. Like this!

OK, that was a gimmee.

Tweaking normal text

The easiest bits of Markdown are for tweaking normal text. If you want to emphasize (or italicize) something you can just surround it in asterisks (*). To bold it just use two (**). Use three to combine emphasis and bolding.

Adding document structure

Beyond writing a short comment, you probably need to add a little more structure to your documents. The easiest way to do this is by adding some headings to break up the sections.

For headings you can start a line with one or more # symbols. The number of #s that you use corresponds to the heading level. So using one # is used for top level headings (or H1 from HTML or many word processing programs). Two of them (##) is an H2, etc…

# This is an H1

## This is an H2

### This is an H3

Lists

Lists come in two varieties, unordered (bulleted) and ordered (numbered). Use lines starting with asterisks (*) to create unordered lists, and lines starting with #. to create numbered lists. You can also use actual numbers instead of the # symbol, but using the symbol allows Markdown to automatically set the numbers on the items, so if you want to reorder the list you just change the order, and don't have to worry about renumbering.

You can use indentation to nest lists inside of one another.

* This is an unordered lists
* The asterisks are turned into bullets
    * Indenting an item makes a sub list

#. This is an ordered lists
#. The #s are turned into numbers
    #. Indenting an item makes a sub list

Horizontal rules

To break up sections of a document you may want to include a horizontal rule. Three or more dashes on a line will do it. Instead of - you could also use * or _.

-------

Links

To display a URL and have it turned into a link you can just surround it with pointy brackets (< and >). To link some regular text you can surround the text in square brackets ([ and ]) and then follow with a URL in parentheses.

<http://www.remarq.io>

[Remarq](http://www.remarq.io)

Images

The syntax for images is very similar to that for links. You just add an exclamation mark to the begining of the link, and then point the URL at an image.

Markdown	Rendered


A whole document

So, putting it all together a very basic Markdown document might look like this.

# Markdown is a great language

There are *so* many things that make it **awesome**. Let me count the ways in
which it is great.

## Easy

Markdown is really just like plain text, so you don't need to know
anything special at all to read it, and you only need to know a little
bit to write it.

## Compact

Markdown is pretty much all about the content, and it doesn't waste any
bytes on styling or other fluff.

## Etc...

There are too many ways to list in this short demo. :)

# Resources

Here are a few links about Markdown.

* [Official Markdown Project](http://daringfireball.net/projects/markdown/)
* [Five Minutes to Markdown Mastery](/articles/five-minutes-to-markdown-mastery/)
* [Why Markdown? A two-minute explanation](http://brettterpstra.com/2011/08/31/why-markdown-a-two-minute-explanation/)

# Shameless Plug

[Remarq](http://www.remarq.io) is the best way to generate professional
quality documents from Markdown.

******

[Check out this very example formated as a high quality PDF with
Remarq.](http://www.remarq.io/pdf/simple-demo.pdf)

[![Remarq
Report](http://www.remarq.io/images/report.png)](http://www.remarq.io/pdf/simple-demo.pdf)

And then when rendered it might look like this: