Writing your blog posts in Markdown with Postmarkdown

February 3, 2012

This post was originally published in the Rambling Labs Blog on February 3, 2012.

Another thing we added to our new site, uploaded back at the end of December, was the ability to write our blog posts in Markdown, which is a text-to-html tool that allows you to write formatted text without actually having to write all the corresponding HTML. Markdown is used for the project wiki pages on GitHub, and can also be used for the project’s readme file.

Most of the time, I don’t like that HTML gets autogenerated for me, since I usually don’t get the results I want. We used to have the site (which was really the blog only) in WordPress, and I never used the autogenerated HTML. In fact, it was quite the opposite: I wrote every blog post in plain HTML.

On the other hand, with Markdown, I can get what I want most of the times. Additionally, Markdown has a beautiful Syntax and if there is any case where I can’t get exactly what I want, I can write only the part I’m having issues with in HTML and not the whole post. That last thing is a big win in my opinion, because I’m not restricted to use one or the other alone.

Now, in order to write our blog posts in Markdown, we used a modified version of the Postmarkdown gem. The gem itself is very useful out of the box and really easy to configure. To include it to your rails app, add this to your Gemfile:

gem 'postmarkdown'

And run this commands:

bundle install
rails generate postmarkdown:install

The posts have to be on the app/posts directory. By default, the root route for the posts in your application is going to be /posts. To change this, add the following line to your config/routes.rb file:

postmarkdown as: :blog

This will change the root route to /blog.

To generate a new post, just run this (the --date parameter will default to the current time if not passed):

rails generate postmarkdown:post name-of-the-post --date=2012-02-03

You can also read more documentation about Postmarkdown in the project’s readme on GitHub.

We had to do some changes to the gem though. For example, by default, the gem assumes that you will write at most one post per day. This isn’t very convenient for us, since sometimes we post 3 or 4 times in one day. So, we changed the date format for both post generation and post lookup.

We also added the tags to the metadata of the posts, and built some additional views, like Archives and By Tags, so that it’s a bit more complete.

We had to migrate the old posts from WordPress to Markdown, but that’s a story for another post.

Enjoy!