Selling markdown to the reluctant learner

If you write on the web then it is safe to assume that you use html to format your text. It can be as simple as wrapping your words around a <strong></strong> tag to make it bold or around <em></em> to add emphasis. Then there are anchor tags for the links to other resources, image tags, headings etc. Writing on the web is more complex than writing on say a piece of paper because you not only have to think about what you are going to write you have to keep in mind to format your words properly as well.

It is also safe to assume that most of you do not type these tags with hand but instead use a text editor that wraps your text around the proper tags. A click of a button and the text is bold. A click of a button and the text is emphasized. A click of a button and …. well you get my point.

While this may all sound simple my limited experience on writing for the web tells me that that every time you leave the keyboard to reach for that button to click you break your typing rhythm. This is where markdown comes in handy. It allows you to concentrate on your words while providing shortcuts to format them.

But this convenience does not come for free. There is a slight learning curve associated with markdown. Though if you take time to learn it can make writing on the web a more pleasurable experience. I will cover some of the most common formatting that we use while writing and show how it can be done in a simpler way using markdown. Hopefully after reading this article you will be encouraged to learn markdown.

On the left hand side I give the markdown syntax and on the right followed by a ‘->’ it’s HTML equivalent.

  1. Headings : In html there are 6 levels of headings. H1 to H6 in the decreasing order of importance.So H1 is the most important heading and H6 is the least important one. Markdown makes it trivial to create headings.#Heading -> <h1>Heading 1</h1> ##Heading -> <h2>Heading 2</h2> ###Heading -> <h3>Heading 3</h3> ####Heading -> <h4>Heading 4</h4> #####Heading -> <h5>Heading 5</h5> ######Heading - > <h6>Heading 6</h6>“#” tells the markdown interpreter to interpret the text following it as a heading and the number of tags give the order of the heading. So a single “#” is h1 while a “##” h2 and so on.
  2. Emphasis : _Emphasized text_ -> <em>Emphasized text</em>
  3. Bold : ** Bold text ** -> <strong> Bold text </strong>
  4. Links : [link text](url to the link) - > <a href="url of the link">link text</a>
  5. Images : ![alt text](image url)-> <img src ="image url" alt ="alt text"/>
  6. Horizontal rules : --- -> <hr>

If you are reading this syntax for the first time it might look a bit cryptic to you but it is actually much better than using a text editor. For example imagine a piece of text

“It was raining hard.”

Now you want to bold the word “hard”. You could either

  1. Stop typing
  2. Reach for your mouse,
  3. Find the bold button on your editor
  4. Highlight the text you want to transform
  5. Finally click the bold button to change the text.

Or just wrap the text inside ** **. To me the markdown methods sounds much simpler.

There are tonnes of markdown editors available on the web. They mostly fall into one of the two categories

  • Eager preview
  • Preview on demand.

The former type of editors display the converted text as you type it. While the latter shows you a preview when you explicitly ask for it. Personally I prefer the preview on demand editors since once you learn markdown the eager preview becomes a distraction. Whatever editor you may chose though I am certain that once you learn how to use markdown it will make writing on the web painless and even enjoyable.

This article only scratches the surface of what markdown can do as the purpose of this article was to introduce you to it’s syntax. If you want to learn more about it check out the reference. I suggest rather that learning it all in one go just look at the ones that you need at the moment this way it will be much more easier to grasp.

Bonus : See the original markdown text for this post and compare it to the rendered screen that you are reading right now.



  • On September 02, 2013