Month: December 2013

What is Markdown?

Markdown is a tool that converts text to HTML using a simple markup language. For example, this:

Formatted HTML

This sample text is bold. This sample text is italicized.

Here’s a list:

1. List item 1.
2. List item 2.
3. List item 3.

Here’s a quote:

Everybody Has a Plan Until They Get Punched in the Face
– Mike Tyson

Here’s some code

if (true) {
   goto 10
}

Represented by this Markdown

**This sample text is bold.** *This sample text is italicized*.

Here's a list:

1. List item 1.
2. List item 2.
3. List item 3.

Here's a quote:
> Everybody Has a Plan Until They Get Punched in the Face

Here's some code

    if (true) {
       goto 10
    }

And this HTML

<p><strong>This sample text is bold.</strong> <em>This sample text is italicized</em>.</p>

<p>Here’s a list:</p>

<ol>
<li>List item 1.</li>
<li>List item 2.</li>
<li>List item 3.</li>
</ol>

<p>Here’s a quote:</p>

<blockquote>
  <p>Everybody Has a Plan Until They Get Punched in the Face</p>
</blockquote>

<p>Here’s some code</p>

<pre><code>if (true) {
   goto 10
}
</code></pre>

The Markdown looks like something you could paste into an email, and that’s the point. It’s human readable, but it can be converted into lovely, well-formed HTML.

Why I ♥ Markdown

Ask any one of my coworkers, and they’ll tell you that I take my documentation very seriously. One of my pet peeves is using Microsoft Word to maintain technical documentation. I think that Markdown has several advantages over Word docs:

Markdown is readable as plain text

I’m a Software Developer, and like most Software Developers, I have developed what is probably an unhealthy attachment to my text editor and to the command line. I like text documentation because it’s versatile. I can view Markdown text from the command line. I can view it in my text editor. I can view it just about anywhere.

I can view it in a web browser. No downloading necessary

We have all experienced this on the web before. You do your Google search. You see a link that looks promising and click it. Then you see this:

If you’re like me, you immediately close that dialog and move on to search results that don’t require any friggin’ double-clickin’.

I think that one of the reasons that Github is so popular is that you can create a lovely, formatted web page by creating a file with some Markdown in it. No muss, no fuss.

It’s text, so I can version it right along with my source code

This solves a lot of problems for us at work. We use a wiki called DokuWiki with a Markdown plugin that supports my favorite flavor of Markdown called Markdown Extra.

This is super useful because we can easily see what changed between versions, who changed it, and when.

It’s text, so I can diff it using my preferred diff tool

At work, we keep documentation on our web component in Word documents. These don’t change a lot, but when they do change, good luck figuring out exactly what has changed. If you’re lucky, the last person to edit the file turned change tracking on, but it’s nowhere near as simple as something like this:

Formatting options are limited so I don’t spend time puttering around with formatting

I think everyone has gone to battle with Microsoft Word over positioning a line break, or numbering a list, or indenting a block of text.

More Markdown for your editing pleasure

I will be posting links to a few Markdown tools and sites throughout the week. For now, here are some links to get you started.

• Here’s a link to the original Markdown page by one of its creators John Gruber:
  http://daringfireball.net/projects/markdown/
• Markdown Extra is a Markdown variant with a few special herbs and spices such as table support:
  http://michelf.ca/projects/php-markdown/extra/
• The Markdown wiki page: https://en.wikipedia.org/wiki/Markdown
• WhatIsMarkdown.com: http://www.whatismarkdown.com/