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.

Markdown Rendered
This text has *emphasis*. This text has emphasis.
This text **is bold**. This text is bold.
This text ***is emphasized and bold***. This text is emphasized and bold.

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…

Markdown Rendered
# This is an H1

This is an H1

## This is an H2

This is an H2

### This is an H3

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.

Markdown Rendered
* This is an unordered lists
* The asterisks are turned into bullets
    * Indenting an item makes a sub list
  • This is an unordered list
  • 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
  1. This is an unordered list
  2. The #s are turned into numbers
    1. 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 _.

Markdown Rendered
-------

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.

Markdown Rendered
<http://www.remarq.io>
http://www.remarq.io
[Remarq](http://www.remarq.io)
Remarq

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
![Remarq Report](http://www.remarq.io/images/report.png)

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:

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.

Shameless Plug

Remarq is the best way to generate professional quality documents from Markdown.


Check out this very example formated as a high quality PDF with Remarq.

Remarq
Report

Get new articles in your inbox

Look as valuable as you are to your clients...
even if you aren't a designer.

Sign up to use Remarq now.

Start My Free Trial