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 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.
Markdown | Rendered |
---|---|
|
|
|
|
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 |
---|---|
|
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.
Markdown | Rendered |
---|---|
|
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 |
---|---|
|
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.