The Basics of Markdown

As I professed my fervent love for Markdown last week, I’ll spare you — go read why Markdown’s great if you haven’t — but to say that Markdown is a quick way to easily create all the niceties of HTML without having to deal with all the annoying traits of actually typing out HTML.

The Syntax

First and foremost, Markdown is just text. That’s its best and most flexible quality. Even when littered with lots of markup — links, headers, lists, etc — it still reads pretty cleanly. This makes it the ideal tool to pass around between all your applications and platforms: your Android phone, iPad, and desktop computer can all read and write it with ease.

  • Headers<h1>, <h2>, etc are simply connoted with pound signs. # This is a title is all you need to create an H1 element in Markdown. The number of pound signs corresponds to the “level” of the title. You can close them too,  if you like that kind of thing, so an H3 could look like: ### This is a title ###. Another alternative is to put a full line of hyphens or equal signs under the line with your title, but that doesn’t allow for the full depth of HTML titles.
  • Unordered lists, <ul>s in HTML, or bullet-point lists in plain English, are created by simply starting your lines with an asterisk. Every successive line that starts with a * will become an <li> within the <ul>.
  • Ordered lists are simply done by writing our your numbers with periods, one per line.
    1. This is the first element 
    2. This is the second

    effortlessly becomes an <ol> wrapping <li>s. Interestingly, it doesn’t actually matter if your numbers are in sequential order or if you have repeats. There just have be numerals and periods there at the front.

  • Links are a bit strange and hard to remember. The anchor text — the words the reader sees go inside of square brackets ([]), while the actual place the link points going inside of parentheses. So a link to the Press Up Twitter pages would look like [check us out on Twitter]( You can specify more, like the title, but I rarely do an don’t want this tutorial to be exhaustive. I’m sure there’s a good nemonic for remembering this, but I just use the fact that I know parenthesis in URLs are problematic in Markdown to keep it straight.
  • Code examples — which are typically rendered in a different font — are bound with simple back ticks: `. (The key just to the left of your numeral 1 along the top of your keyboard.) This single feature is the biggest reason I LOVE Markdown. So much easer to type `do_thing` than <code>do_thing</code>.
  • Images look like links, but start with an exclamation point: ![Title](Link URL).
  • Block quotes start with a single starting greater than sign: >.
  • There’s tons more. You can create code blocks with a simple back tick fence ``````. I could go on, but think we’ve covered all the basics.

It’s worth calling out that one of the oddities of Markdown is that as a language without a standard body, it has dialects. The most dominant among the cool kids scene is the so-called “GitHub Flavored Markdown” — sometimes abbreviated as GFM, which added the back tick fence concept — but there are many others. MultiMarkdown deserves a mention.

Making your Markdown into HTML

icon_256x256There are tons of way to make you Markdown into HTML. One of the most common, though unrecognized ways, is to use many many comment forms on the web. But leaving a reddit comment isn’t an efficient way to turn a text into HTML.

Your options, other than that, are very diverse. There a tons of text editors that will export to HTML from Markdown out of the box. I’m typing this in Byword, a Mac app which does, but there are almost uncountable others. I took the screenshot at the top from Ulysses, another Mac app. I don’t really know about Windows, but MarkdownPad looks nice and was my first Google result.

Failing your having one of those on hand, another great and simple option is the massive number of Markdown to HTML pages online. The best is probably, though John Gruber’s (he’s the “father” or Markdown) “Markdown Dingus” is the classic.

I hope you now feel able to start creating your first few documents with Markdown. I won’t lie, at first it can feel slower and awkward than your own improvised syntax or your familiar WYSIWYG experience in Word or your CMS. But the simplicity, commonness, and flexibility of Markdown truly can’t be beat.

About David Hayes

David likes learning, solving hard problems, and teaching. He bikes a lot, and lives in (and loves) Colorado. You can find him on Twitter as @davidbhayes and check out his latest hobby-project, Quodid, a monument to his love for pithy bits of wisdom.

Leave a Reply

Your email address will not be published. Required fields are marked *