12/15/2014 - No Comments!

Introduction to Markdown

Markdown Illustration

I've noticed more and more text-based web applications have been integrating support for the Markdown language over recent months. Most notably the project management software I use in my daily work week Pivotal Tracker. I attended a team Tech Talk on the subject hosted by my coworkers and what follows are my takeaways and notes from learning this new skill.

I would strongly encourage anyone reading this article to spend a few minutes learning Markdown yourself, as I foresee it becoming increasingly common across the web. It enables a very powerful set of composition features with little knowledge required. Since learning about Markdown, I've integrated it into this personal WordPress blog (you are here) as a means to quicken and simplify my own writing workflow.

Why Use Markdown?

So, why use Markdown? What is the advantage of writing Markdown over straight HTML for articles such as this? A valid question, and one that I asked myself when I was first introduced to the concept. The answer was provided to me as follows:

  • Markup is simpler & less intrusive when actually creating content, compared with HTML. It appears visually as you would expect the output to be, without intrusive or complex markup.
  • Markup is great for content, but not so greta for more stylized websites. When each paragraph differs stylistically from the last and there are more custom, on-off elements than not, you may be better off using straight HTML.
  • It is easy to share Markup code and equally easy to introduce more powerful, dynamic features using Jekyll and other plugins.

Markdown Syntax

Markdown is a text-to-HTML conversion tool for web writers. It allows the author to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). Markdown’s syntax is comprised entirely of punctuation characters. These characters were carefully chosen so as to look like what they mean. For example, asterisks around a word actually look like emphasis. It's considered a writing format, instead of a publishing format, and not intended as a replacement for HTML. It only offers a small subset of HTML tags, those most common in the writing of prose.

Because of this limitation Markdown allows for the use of regular HTML interspersed with markdown. It is important to note however, that you cannot intersperse markdown within block-level HTML (p, div, table, etc.). This only works for span-level elements such as spans or a-tags.

The more common elements supported by Markdown include paragraphs, headings, blockquotes, lists, code, horizontal rules, emphasis, images and links. Markdown uses an empty line break as a means to switch the context between block elements. This makes for a very clean and easy to read markup language, much simpler to grasp at first glance by us folks without a computer science degree.

Nice Features

Ampersand and Bracket support

You no longer need to stop everything to write out HTML compliant ampersand code, which can be very painful. Things like this also take away from the writing process and intrude on the creative flow. Markdown takes care of these pesky things for you. Write "&" and Markdown will auto add the proper HTML for you &. Nice.

Reference Links

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link.

This is [an example][id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/ "Optional Title Here"

Automatic Linking

Another neat feature is the automatic addition of link. To enable this, you need to be using the Jekyll extension. With it, anything in your article preceded by http:// or https:// will automatically become a clickable hyperlink. You can also add the alt and title tags. More on this here: http://daringfireball.net/projects/markdown/syntax#link.


Like many open-sourced web languages, the web community has extensively built upon the Markup language. Jekyll, Kramdown and other extensions exist to make the language even more custom and applicable to your use case.

Further Reading

  • Daring Fireball. The creators of Markdown & all related documentation, straight from the source.
  • Dillinger. Dillinger is a cloud-enabled, mobile-ready, offline-storage, AngularJS powered HTML5 Markdown editor.
  • WP-Markdown. WordPress Plugin which enables you to write posts in Markdown, and translates that content into HTML when you save. That content is then reverted back to Markdown when you edit it. Once you have the plugin installed, simply activate it and enable Markdown for areas of your site you wish to have it available.
  • WordPress.com. Another handy Markdown quick-reference table.
  • Pivotal Tracker. An introduction to Pivotal Tracker flavored Markdown.

Published by: Ray in 2014, Learning, Presentation Notes