🔠 Markdown Demystified

By Heliomass | | 5 minutes

In this article, you’ll find a quick rundown of what Markdown is, why you’d want to use it and how to use it.

What is Markdown?

In 2004, John Gruber developed simpler way of writing web pages that didn’t involve resorting to HTML. He set out to create a new markup language with the simplicity of HTML’s basic styling and hyperlink capabilities, but when you looked the source it would still remain human readable. It would have a minimal syntax, so it’s really easy to learn.

This was Markdown.

Consider the following block of HTML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

<h1>
    Page Title
</h1>
<p>
    This is some text, some of which is <b>bold</b>
    and some of which is <i>italic</i>.
<p>
</p>
    Oh look, here's <a href="http://www.emergencykitten.com">a link</a>!
</p>
<p>
    And a list of items:

    <ul>
        <li>Item 1</li>
        <li>Item 2</li>
        <li>Item 3</li>
    </ul>
</p>

Here’s exactly the same styled text, but in Markdown:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# Page Title

This is some text, some of which is **bold** and some of which is _italic_.  

Oh look, here's [a link](emergency-kitten)!

And a list of items:

* Item 1
* Item 2
* Item 3

[emergency-kitten]: http://www.emergencykitten.com

Look how much more readable that is! Using Markdown helps you focus on the content.

Why Markdown?

If you want to markup your text, there are already existing solutions out there (think HTML and LaTeX), so why try and reinvent the wheel?

At the beginning of my final year year at university, one of our lecturers gave us an insightful talk on how to write up our dissertation. Along with the wise words “To fail to plan is to plan to fail”, he helped us cover some of the options available to us. Some of the options on the table:

  • Microsoft Word: At the time not all that stable and bad at handling large documents. Who fancied the thought of their 90 page document suddenly becoming corrupted? Also, not free, which matters to a student.
  • LaTeX: Powerful and widely used in the academic world, particularly in Mathematics and Computer Science. However, tricky to learn with a massive learning curve.
  • HTML: We all know how much “fun” it is to write a website in HTML. Can you imagine how much fun it would be to write an entire dissertation in it?

Personally, I ended up going with LaTeX as the choice for my own dissertation where I spent the first couple of weeks actually learning the technology instead of working on the dissertation content. It was worth it though. Most of my peers went with Word. No one (to my knowledge) chose HTML.

And that brings us back to Markdown. I consider Markdown brings the best of all the above options:

  • Small file size; It’s basically text!
  • Even raw Markdown is incredibly readable.
  • You don’t need a WYSIWYG editor, but they exist if you still prefer to work that way.
  • Its simplicity means it converts well to other formats, such as HTML, RTF and PDF, and pretty much anything else you can think of.
  • You can apply whatever styling you want to the rendered Markdown, similar to the way CSS styles HTML.
  • Server-side plugins mean you can write your entire website in Markdown and have the pages served up to your end user as HTML.

I use Markdown for many things. For example, this post is written entirely in Markdown. My email client supports markdown. I also maintain my CV as a Markdown document which is then processed into an HTML file with a custom stylesheet applied to it. From there I can upload it somewhere or save it as a PDF. I write notes in Markdown, which I can then share with people as a Microsoft docx file.

Learning Resources

The best way to quickly experience Markdown is to try it for yourself. Once you’ve mastered the basics, there are many resources out there to help you further develop your skills!

Epilogue: The Markdown War!

OK, so maybe calling it war is overdramatic, especially when you consider the ongoing Vi(m) versus Emacs debate. But, once Markdown caught on it was clear that people wanted it to do more. Things that Markdown doesn’t do in its native form:

  • Tables
  • Metadata
  • Captions

Extensions to Markdown do exist, the most popular of which seems to be MultiMarkdowncreated by Fletcher T. Penny. Lots of applications support this Markdown extension, including two of my favourites: Byword and the exceptionally powerful Editorial.

And then, Jeff Atwood of Coding Horror fame came along and lamented the lack of an official standard for Markdown beyond what John Gruber had already proposed. There was a certain amount of friction between Gruber and Atwood over the name for this Markdown extension, but in the end everything was resolved amicably and Atwood’s team went on to specify what would come to be known as CommonMark.

And that’s not all. Other popular sites have adopted their own specialised flavours specific to their own needs, for example on GitHub.

Which of these variants ends up being adopted as the most widespread remains to be seen, but what’s important is they’re all backwards compatible with the original.

Conclusion

Markdown is something I use on a daily basis, because I find it useful, concise and elegant. But, I wanted to at least try and frame it as something which reaches beyond the tech profession, as something useful for writers and academics, lawyers and accountants. Pretty much anyone who wants a lightweight way of writing documents and also wants to share them in any format under the sun, from PDF to Microsoft Word, from Google Docs to LaTeX.

Markdown is cool.