Markdown and you

This post is all about markdown and why you should use it. It'll introduce 3 people you should care about if you don't already know them.

First of, John Gruber from Daring fireball invented markdown a while back. For those who aren't aware of this, web pages are written in HTML. The 'M' in HTML stands for markup, as in Hyper Text Markup Language. A markup is extra characters added to text to define things (structure and formatting in the case of HTML) about the text.

So Gruber was blogging and was tired of spending so much time marking up his text just to define structure or style and invented something he called markdown in reaction to markup: a simpler way to write with the same information. For example, instead of writing <emp>italic</emp> you just write _italic_ and the markdown processor translates it into proper HTML. So you can write in a more natural way.

The other goal of markdown is that the text should be readable easily without being processed, i.e., even with the markdown. That way you can read the 'raw' text easily and you don't need a processor or a web engine to understand the content.

If you're interested, and you should, check out markdown for a list of the few simple rules. I'm writing this blog post in markdown. In fact, I've been using markdown for years now. Why? Read on.

I've used various programs to gather information over the years: ideas, snippets, lists of things, things I want to remember, etc. Then after a few years the software I was using stops being updated for the latest operating system, or doesn't offer a mobile version, etc. Then you're stuck trying to export everything into another program. That's if it's possible to export, and in any case it's a long and frustrating process. When you've done this twice or more, you start looking for a better solution. For me it was markdown, and now I'm the owner of what I write. Because I write everything in plain text files, I can access everything from any text editor I want and I will always be able to access it in the future.

Everything I want to remember, snippets, lists, etc. I write in text files. If it can use structure or style, I write it in markdown. Simple text files aren't dependent on any fancy program so they're unlikely to become inaccessible for a while. You can even change your preferred text editor (something I did many times) and you're still good. Searching through text files is easy and fast. I use a super fast application called nvAlt by Brett Terpstra which search blazingly fast. I put everything in a single folder on Dropbox so I can access everything from anywhere on any device. There are many editors that support markdown, both on desktop and on mobile.

If you're interested in going the markdown way, there is a great book by David Sparks & Eddie Smith.

Markdown basics


Sections' titles, or headers, are defined with the # character. One # is the biggest title, or H1 in HTML, ## is the second level, or H2, etc. So something like this:

### This is a level 3 title

Is transformed into this after processing:

This is a level 3 title


When you want to make something bold you simply surround it with **, like this: **this is bold** -> this is bold.

For italic, use _, like this: _this is italic_ -> this is italic.

For bold-italic, combine them: _**this is bold-italic**_ -> this is bold-italic

For code inline, use the back tick `, like this: `NSUserDefaults` -> NSUserDefaults.

For a code block, use 3 back-ticks on the lines before and after the block, like this:

if NSFileManager.defaultManager().fileExistsAtPath(audioFileURL().path!) { print("The file already exists!") shouldSegueToSoundPlayer = true }

Shows as this:

  if NSFileManager.defaultManager().fileExistsAtPath(audioFileURL().path!) {
      print("The file already exists!")
      shouldSegueToSoundPlayer = true

To insert a link into text you use this syntax: [link text](link).

For example, [Apple]( -> Apple

This is the 'inline' version, you can also choose to put all the links at the bottom of the text (which is a good idea if you link more than once to the same URL). In this case you define a name for the link and put the link at the bottom:

This is a paragraph where there is a link to [Apple](apple) where you used the link name 'apple'. Anywhere else in the text (usually people place these at the end of the text, but it's not obligatory).


Seeing the formatted output

As you see, you can easily read the raw markdown text. The markup doesn't make the text unintelligible. But what do you do when you want the processed text? There are many options depending on what you trying to do.

For example, I'm writing this blog post in markdown, and I don't have anything special to do to publish it because the blogging platform1 I'm using supports markdown. So I just press publish and everything is properly translated.

Many text editors support markdown preview, which means that you can see what your processed text will look like, often side by side with the raw markdown. Atom for instance, supports this, as does MultiMarkdown while SublimeText sends the preview to your web browser. You can search for more markdown editors easily.

For a more powerful tool you should really try Marked which offers many great export options and lots of features.

You can also have a formatted quicklook preview by using this plugin.

So, markdown is much more than just GitHub ‘readme’ files. It's a great way to add structure and formatting information to plain text files which means you can use it to save lots of information in a future-proof and portable way. You should really look into it.

[1]: I am using Armadillo as a blogging platform now.

blog comments powered by Disqus