Hi, my name is Mike McLin, and in this video I am going to talk about Markdown, what it is, why I use to despise it, and why I now love it. I’ll walk through some basic Markdown examples, but more importantly, I’ll explain what Markdown really is, and why you should embrace it. So let’s get started.

Starting out with Markdown Syntax

My first experience with Markdown was probably similar to most other web developers out there. I decided to get on the Github bandwagon (pun intended) and noticed that one of their first recommended steps when creating a repository, was to create a README file, and the README file was suppose to be in Markdown syntax.

So, I immediately entered Markdown into my Google machine, and found the Daring Fireball site that has all the information about Markdown. Right off the bat, I see the first sentence “Markdown is a text-to-HTML conversion tool for web writers” and I began to frown. I mean really? Do we really need another text to HTML tool out there? I already had to learn wikitext, textile, bbcode and so on… Now, I have to learn another one? I was thinking, isn’t HTML a simple enough language where anybody that has the skillset to use GitHub should be able to learn a little bit of HTML syntax?

Regardless, I proceeded, because the cool kids were using GitHub, and I wanted to be invited to their parties, if only for the cake. So, I jump straight over to the syntax section to begin my reluctant journey. I notice they have an overview section that includes the philosophy for the project. I roll my eyes as I skip over to the Block Elements section, so I can actually start writing code, because the clock is ticking, and I don’t have time for this.

Learning the Markdown Syntax Language

I see that paragraphs are just blocks of text with a blank line separating them, what a shocker. OK, now I see there are 2 different ways to create headings. We can use this first method which is called setext (or however you pronounce it). It uses either either equal signs or dashes on the line below the text to turn it into a heading. What a waste of time and characters I thought. OK, I also see that we can use pound symbols before the text to declare a heading which is apparently called the atx style. Even better, I can place pound symbols after the heading too, so it almost feels like HTML. Perfect!

I move on and see that I can create a blockquotes, but I have to put these greater symbols in front of the text on each line of text…what a pain. Then I realize I only actually need to place it on the first line, and I’m thinking, ok I can handle that. List items work as I expected, I can use either an asterisk, plus symbol, or a dash, and decide I’ll use the dash because it doesn’t require the use of the shift key.

Now, I see ordered lists actually have the number preceding them, and I immediately think how unintuitive. Now, if I need to insert a list item somewhere in the middle of the list, I have to retype all the following numbers. Luckily, I scroll down and notice that any number will work. Perfect, I’ll just use all 1’s, like this example.

Eventually, I find my way down to the span elements. Emphasized or italic items have a single asterisk wrapping them, while strong or bold-faced items have a double asterisk surrounding them. Pretty common stuff.

Finally I come to the links, and see that I need to place the link text in brackets, and then place the url in parenthesis behind it. I scroll down and see something about reference-style links, where you actually place the url of the links somewhere else on the page, and I chuckle to myself as I think, why are they making something as simple as links so trivial. Did I mention I hate that I am having to learn this right now.

So, I create my README file, and it looks something like this. I download a plugin for my text editor that shows me the HTML preview of the Markdown, and I am satisfied with the HTML result, but still loathe Markdown.

I finally come full circle about Markdown

So, a few months go by, and I see someone ask what Markdown is on a forum or something, and I see someone respond saying that the purpose of Markdown is to make your text files easier to read…and that’s when it hit me. I had been using Markdown completely wrong, and misunderstood the whole project. I hurry back to the website that introduced me to Markdown and this time read the philosophy…and there it was in plain text… “Readability, however, is emphasized above all else.”

This completely change my outlook on Markdown. I mean, I love to document stuff. I get all nerdy with my CSS comments, and I’m not the only one. Take a look at any popular framework, like HTML5 Boilerplate or Twitter Bootstrap and you’ll see that they are meticulously commented. It makes us feel warm and fuzzy to create these beautifully spaced and formatted comments. Unfortunately, not everyone creates comments in the same fashion, so it gets hard to decide how to format your comments. Well, Markdown has solved that problem, at least for our documentation and README files.

So, I reread the Markdown syntax and realize that it usually gave me 2 options on how to format something, and almost every time I picked the wrong option. Maybe not syntactically, but spiritually, based on the motives of the Markdown project, I picked the wrong choices.

So, I decided to use the setext style headings, and not skimp out on those greater-than characters for my blockquotes. I began to use real numbers for my ordered lists, use those reference-style links that I previously thought were unnecessarily complex, when I wanted to use anchors in a paragraph.

Now, I look at this simple text file, and it is beautiful, and easy to read. If I compare the same document written in HTML, there is no comparison when it comes to readability. So, now I embrace markdown, and understand the need for it.

So, thats the end of my Markdown journey. My name is Mike McLin, and I hope this helped you understand Markdown language a little better, and hopefully you’ll agree with me, that it is a great tool in our development community.