Markdown: The Ins and Outs

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

Paragraphs

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.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.

Simply becomes:

<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed
do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.</p>

<p>Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.</p>

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:

Lorem ipsum dolor sit amet, consectetur.
Adipisicing elit, sed do eiusmod tempor incididunt.

Becomes, quite jarringly:

<p>Lorem ipsum dolor sit amet, consectetur. Adipisicing elit, sed do eiusmod tempor incididunt.</p>

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:

Lorem ipsum dolor sit amet, consectetur.<space><space>
Adipisicing elit, sed do eiusmod tempor incididunt.

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

Headings

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

# Heading One
This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.

## Heading Two

This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.

### Heading Three
#### Heading Four
##### Heading Five
###### Heading Six

Becomes:

<h1>Heading One</h1>
<p>This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.</p>

<h2>Heading Two</h2>

<p>This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.</p>

<h3>Heading Three</h3>
<h4>Heading Four</h4>
<h5>Heading Five</h5>
<h6>Heading Six</h6>

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

Heading One
===========
This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.

Heading Two
-----------
This is a paragraph. Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor incididunt ut labore
et dolore magna aliqua. Ut enim ad minim veniam.

Blockquotes

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 >:

This is a normal paragraph.

> This is a blockquote paragraph.

> And the blockquote continues here, too.

…Which converts to:

<p>This is a normal paragraph.</p>

<blockquote>
    <p>This is a blockquote paragraph.</p>
    <p>And the blockquote continues here, too.</p>
</blockquote>

Code

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 < and > to > etc.

This is a paragraph with a bit of `<strong>CODE</strong>` in it.

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

Another paragraph, but with a code block above it.

<p>This is a paragraph with a bit of `<strong>CODE</strong>` in it.</p>

<pre><code>&lt;?php
$name = $_GET['name'] ?: 'World';
echo "Hello $name &amp; everyone else!";
?&gt;
</code></pre>

<p>Another paragraph, but with a code block above it.</p>

Lists

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:

I will need:

* Snakes
* Scorpions
* Hamsters

Then, I can begin my plan to rule the world:

1. Aquire hamsters  
2. Train snakes to ride hamsters  
3. Rule the world

<p>I will need:</p>

<ul>
    <li>Snakes</li>
    <li>Scorpions</li>
    <li>Hamsters</li>
</ul>

<p>Then, I can begin my plan to rule the world:</p>

<ol>
    <li>Aquire hamsters</li>
    <li>Train snakes to ride hamsters</li>
    <li>Rule the world</li>
</ol>

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:

Here's some *italic* text, and more _italic_ text. Some **bold stuff** here; plus a __little__ bit more.

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

[Google](http://google.com)

<a href="http://google.com">Google</a>

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

![The Google Logo](http://google.com/logo.png)

<img src="http://google.com/logo.png" alt="The Google Logo">

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
<?php
$name = $_GET['name'] ?: 'World';
echo "Hello $name & everyone else!";
?>
```

Conversion

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.