Code blocks in Markdown

As a technical blogger, I often want to display snippets of code. I use the Jekyll static site builder to create my site. Jekyll consumes blog post content written in Markdown and pumps out static HTML pags. Markdown has a syntax for denoting code:

Single line code snippets get marked with single backticks, like `this`.

Conventionally, this markdown would create HTML markup that looks something like this:

<p>Single line code snippets get marked with single backticks like <code><pre>this</pre></code>.</p>

Originally, multi-line blocks of could would be denoted by indenting each line of code at least four spaces, or a tab.

Your text content around the code does not require special syntax. The multi-line code would look like this:

    // four spaces of indent
		// .. or a tab or two depending on your tab size
    if( javascript === true ) {
        throw 'This is a ridiculous example';
    }

... and you could continue your prose as before.

The above Markdown would generate HTML like this:

<p>Your text content around the code does not require special syntax. The multi-line code would look like this:</p>
<code>
	<pre>
    // four spaces of indent
		// .. or a tab or two depending on your tab size
    if( javascript === true ) {
        throw 'This is a ridiculous example';
    }
	</pre>
</code>
<p>... and you could continue your prose as before.</p>

Since its inception, various extensions to Markdown have been proposed. Github Flavoured Markdown has become one of the more popular. It includes support for “fenced code blocks”, which allow for a chunk of code to be marked up using “fences”: a line of three backticks before and after the code block. This more explicit demarkation makes it easier to control the indenting within your files. GFM’s code fences also allow authros to specify which programming language their code snippets are written in. Take a look:

```javascript
// The indenting is much simpler, now
if( javascript === false ) {
	throw "This one isn't much better";
}
```

The syntax highlighting will only work when the Markdown gets transformed to HTML using a build process aware of this expectation. Fortunately, Jekyll was built with this in mind. Jekyll configuration allows the site’s maintainers to chose a Markdown parser and also a syntax highlighter. As I publish the site using Github Pages, I use the same toolchain locally as their public build process. At the time of writing, they use Kramdown to parse Markdown, and Rouge to perform the syntax highlighting. The above Markdown, will generate HTML like this:

<div class="highlighter-rouge"><pre class="highlight"><code><span class="sb">```</span>javascript
// The indenting is much simpler, now
if( javascript === false ) {
	throw "This one isn't much better";
}
<span class="sb">```</span>
</code></pre>
</div>

Coders tend to find self-referencial code and project names interesting and funny. My contribution to this meme is showing how to mark up Markdown in Markdown:

``````markdown
```markdown
Multi-line code gets fenced with triple backticks and labelled with the language, in this case "markdown".
```
``````

Inspired by this page from the Kramdown documentation