Installing BlueCloth: Use Markdown in Ruby on the Mac

If you find yourself writing text that you’ll eventually post to the web, hopefully you’ve heard of text-to-HTML translators like Textile and Markdown. These tools take plain text formatted with a very light syntax of special characters that can generate formatting like bold text, bulleted lists, and so forth.

I am a big fan of Textile and use it frequently when I set out to write something new that I plan to post to the web (like this post). I’m coming around to see the value in Markdown, however, because it does a better job of taking existing text and translating it to HTML without any manual cleanup. It works especially well when copy-pasting text in e-mail that you want to post online.

Both of these are very useful when writing web applications, since they allow you to convert plain text input from the user into something formatted when displayed in the browser. I’ve used them both from within Ruby scripts, but unfortunately there seems to be an issue with the Ruby gem port of Markdown (BlueCloth). The standard gem install does not seem to do what’s necessary to allow you to use BlueCloth in your own apps or from the command line. (RedCloth doesn’t have this problem.)

So, here’s what I did to get around it…first, install the gem.

sudo gem install bluecloth

If you hit an error on that step, follow this tutorial for installing Ruby on your Mac. Then, run the BlueCloth installer.

sudo ruby /usr/local/lib/ruby/gems/1.8/gems/BlueCloth-1.0.0/install.rb

At this point you should be able to use BlueCloth from within your own Ruby scripts. But let’s take it a step further and enable the bluecloth command line app.

sudo chmod +x /usr/local/lib/ruby/gems/1.8/gems/BlueCloth-1.0.0/bin/bluecloth

At this point it’s runnable, but it still needs to be added to your PATH. Add the following line to your .bash_login file:

export PATH="/usr/local/lib/ruby/gems/1.8/gems/BlueCloth-1.0.0/bin:$PATH"

Woo hoo! You can now use BlueCloth in your Ruby apps and call bluecloth directly on the command line.

Note: According to the documentation, RedCloth is supposed to be capable of rendering Markdown-formatted text via additional options. I could not get this to work, and from what I have read not all of the Markdown syntax is supported anyway.