Markdown and vim

Just recently a fellow student asked me, if I’d ever used Markdown before. Of course I had. As fan of DVCS and their web sharing platforms (of course I talk about Bitbucket and GitHub), one is bound to stumble upon them, especially when one also uses rails for development. Every new rails project is set up with a generic Readme.markdown.

And Markdown itself is great. It’s kept as simple as possible but still is pretty powerful when it comes to formating easy text. The formating is done by a parser that parses Markdown into well formated XHTML and there you have a neat layout for all kind of lists, and type settings, Headings, etc. using nothing more than simple ASCII symbols that even make perfect sense when reading it unparsed. Just have a look at an example:

An Example
==========

See how a simple text file is turned into a beautiful *XHTML* file using
nothing more than **simple** ASCII methods. On can also use `inline code` or
even Codeblocks:

    public static void main(String args[]) {
        System.out.println("Somehow I always use Java examples");
    }

Of course, my all time favorite:

> Quoteblocks
> Nice for quoting clever people

Then there are (this is worth a subsection)

Lists
-----

1. Numbered
1. Lists
1. And I hate keeping track of counts
1. And why should I
1. It is done for me!

and

* Plain
* Old
* Bulletin Lists
* All of them with
* nesting capabilities!

Oh, and did you ever [Visit my blog?](http://pygospa.wordpress.com).

### There is so much more

e.g. yet a deeper subsection. And it won't stop there. Try your luck with four
hashtags 😉

I could just paste the parsed code for comparison, but instead I’d rather like to give you an example rendered HTML page with proper CSS styling. Isn’t this beautiful?

Screenshot of parsed Markdown in Bitbucket

How can one not love this?! Best of all, when using vim to edit Markdown files there is a syntax highlighting scheme available. This makes Markdown code even more fun to read in unparsed format, which is why I more and more tend to write my simple text files with notes for me in Markdown.

Screenshot of vim displaying markdown

Now as you may notice, .markdown is a pretty nasty file extension. Is that really the file extension for Markdown? And if so, what where the guys thinking?

Now the first question is tricky, as the guys inventing Markdown, i.e. John Gruber and Aaron Swartz

where actually thinking this when doing so:

Markdown isn’t meant to take over the format of a file, it’s a way to subtly add information to the plaintext. Really, the presence of Markdown is metadata, not a file format.
…
No one opening a text file will be confused if they find Markdown syntax, it’s pure bonus.

In this sense, it makes sense to use “.text”, “.txt”, or whatever other plaintext extension is relevant.
…
An editor which knows nothing about Markdown won’t care about the metadata and won’t be confused by the variety of “non-standard” extensions, but will display and edit the plaintext just fine.

In my opinion that is an idea that deserves to be supported. Now, I’m using vim as my default editor (as you can see in on my blog header). Vim behaves somewhat atypical for a *nix originated app when it comes to recognizing files – it does so by using the file’s extension.

Of course if you think about it a bit further it makes totally sense. How else to differentiate between C and C++ (or sometimes even Java)? What about XML, and HTML, etc. There are many file formats that are pretty similar.

So when recognizing Markdown, you again come to the need for a recognizable extension. You can of course always fall back to setting it yourself, simply type

:set syntax=markdown

But I for once find this pretty cumbersome. So I am in need for an extension. If you google for it, you’ll find a pure variety of possibilities:

• .markdown
• .mdown
• .mkdn
• .md
• .mkd
• .mdwn
• .mdtext

As a friend of keeping it short and simple, I’m an advocate for .md. It’s neat, and even the authors at Wikipedia seem to like it, as they claim that .md is the proper extension for it.

Screenshot of ‘Infobox’ wikipedia

But, vim of course uses .markdown. After putting up with it for a while I’ve decided that I’d change that, which of course is easy as pie. All you need to do is start up ~/.vimrc on your favorite editor, and add following line to it:

au BufRead,BufNewFile *.md set filetype=markdown

And there you go, all ready and set to work with Markdown in a really comfortable way. Keep in mind that with this easy-to-use tool you can write excellently formated Read-Me files for Bitbucket or GitHub. But beware! It’s highly addictive! Once started to just using it to spice up your repositories you may end up writing all your text files in Markdown. And this seems to be true not only for computer nerds, but as it turns out, also for visually impaired people, as Steven Aquino debates on an TidBITS article titled With Markdown, Even the Blind Can Write:

Markdown has changed my life for the better. Not only is it easier to work with than graphical interfaces given the limitations of my vision, but it has caused me to embrace plain text for nearly all of my documents.