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 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.
||This text has emphasis.|
||This text is 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
#s that you use corresponds to the heading level. So using
# 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 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.
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
To display a URL and have it turned into a link you can just surround it with pointy
>). To link some regular text you can surround the text in square
]) and then follow with a URL in parentheses.
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.
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.
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.
Markdown is pretty much all about the content, and it doesn't waste any bytes on styling or other fluff.
There are too many ways to list in this short demo. :)
Here are a few links about Markdown.
Remarq is the best way to generate professional quality documents from Markdown.