7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. Tools & Tips

Markdown: The Ins and Outs

Scroll to top
Read Time: 8 mins

Markdown is a shockingly simple markup language that allows you to write, using an easy-to-read, easy-to-write, plain text format. This format can then, in seconds, be converted into another markup language, such as HTML!

If you're not familiar with it, let me teach you about it today!

Markdown does a fantastic job of getting out of the way.

Markdown does a fantastic job of getting out of the way. I'm sure everyone has, at some point, emphasised text in a plain-text document by surrounding the phrase with an asterisk, *like so*. That's exactly how it works in Markdown! Providing extra emphasis (bolding a word) is as simple as **doubling up on the asterix**.

It's no surprise that Markdown's philosophy is to produce content, which can be "published as-is, without looking like it's been marked up with tags."

The benefits should be obvious to anyone who's tried writing web-based content and had to worry about formatting it, too. <em>text here</em> is simply too hard to type, once you're brain is in its flow - not to mention how the frenzy of HTML tags which plague a document can ruin readability while you're proofing a document.

A number of Markdown editors exist, both web and desktop-based, but you can, of course, use any old text editor. The only benefit that specific Markdown editors provide is a live-preview of the generated HTML, and, typically, some level of syntax highlighting.

If you want to try out the examples below, refer to the official Dingus browser-based converter.

The Markup


With Markdown, text is automatically converted into paragraphs where blocks of text are separated by a blank line. And not just by several <br> tags like WYSIWYG's of days-gone-by, but real semantic <p> paragraphs. It's almost like black magic.

Simply becomes:

One small oddity with Markdown is how single line breaks are handled. The Markdown philosophy is that the browser should handle line breaks, and no-one else. So the following text:

Becomes, quite jarringly:

If you absolutely must insert a line break, a work-around is provided: simply add two spaces to the end of the previous line, like so:

A number of Markdown "flavors" can handle line breaks in ways you'd expect, but more on that later.


Begin a paragraph with a #, and that paragraph becomes a header. The number of # signifies the heading level number (<h1>, <h2> etc.)


An alternative syntax is also provided for <h1> and <h2>, like so:


One of Markdown's major influences is plain-text email, and this is blaringly obvious, when you see that blockquotes are formatted exactly as they are in email: prefixed with a >:

...Which converts to:


You can deliminate small inline code snippets, using the ` character around code.

Larger blocks of code can be defined by simply indenting the code up a level (at least one tab/four spaces) - the indentation level will be removed. Markdown automatically escapes all special characters inside a block of code, meaning that you can safely just copy in blocks of code without manually escaping < to &lt; and > to &gt; etc.


Another true example of how Markdown just comes naturally is in how you specify a list. Simply start a paragraph with a * (or +, -) to create an unordered list. Use numbers, 1., 2. etc. for ordered lists:

Inline Text Elements

We already covered italicising and bolding text at the start of this article (* and **), however, you can also swap the astericks for underscores, if that's more your thing:

Links are nice and simple in Markdown (if you can commit to memory whether it's the square and round brackets which come first…):

To display an image, prefix the link code with a !:

Markdown Doesn't Get In Your Way

Markdown is very lenient, when it comes to breaking out of its markup and just using HTML instead. If you need to include a table, include it in HTML. Or, if you'd rather write your links in HTML-format, you can do so. Markdown is smart enough to know when you mean to include HTML, and it works around it.

Markdown also auto-escapes characters, such as &, < and > into the HTML entity form. It even intelligently converts common character combinations into what you really mean.

  • Three dots will automatically become an ellipsis: …
  • Two hyphens will become an en-dash: --
  • Quote marks will become the "fancy", curled versions of themselves.

Flavours & GitHub Flavoured Markdown

A number of alternative Markdown "flavours" exist, which extend the default set of Markdown rules. A common extension is easy line-breaking, as described above. One of the most well-known Markdown flavours is GitHub's Flavoured Markdown. This is used to markup user input everywhere on their site. As well as including improved line-breaking support and a number of customisations specific to GitHub, my favourite feature is their alternative to code fencing, which also allows you to specify a syntax for highlighting. Simply surround a code block with ``` on either side, including the language at the start, like so:

```<?php $name = $_GET['name'] ?: 'World'; echo "Hello $name & everyone else!"; ?>```


The Tuts+ Markdown converter can be found here.

The official converter is written in Perl, and is available for download on the Markdown homepage at Daring Fireball. Several other Markdown converters also exist, for a multitude of different languages - from C...to Ruby... to JavaScript... to PHP. A full list of implementations can be found on Wikipedia.

One popular Ruby implementation is RedCarpet, based on the C library, Sundown, which provides a very simple way to customise the output of the generated HTML to produce your own "flavour" of Markdown.

Recently, I used this library to created a Markdown converter, which accepts GitHub Flavoured Markdown (to allow specifying a code language for syntax highlighting), and outputs the converted HTML in the specific style required by the Tuts+ sites. The Tuts+ Markdown converter can be found here. If you've ever written a tutorial for this site, definitely use it!

In fact, this article was written in Markdown, using the popular Mou Markdown editor for OSX.

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.