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.

Converting HTML files for a wiki? Here’s a script

I can’t be the only person who has had these thoughts:

Wow, this intranet is so 1998 I may as well be listening to rap-metal. It’s a random collection of static HTML pages…no one knows what’s out there and none if it is searchable.

My favorite solution to this quandary is a wiki. For the un-familiar, a wiki is essentially simple web site that can be easily added to or changed by anyone who visits the site. Each page usually has an Edit this page link (or somesuch) on it which takes you to a screen where you can type in some new info (or fix what’s there).

For added fun, most wikis support a way of adding formatting to the text you contribute. I prefer one called Textile, but Markdown is an excellent choice as well. But let’s pretend you’re having this thought:

This wiki stuff sounds super, and this Textile thingy looks neat, but we have a lot of worthwhile info in our random collection of static HTML pages…is there an easy way to get that stuff converted onto a wiki?

The answer is: “sorta.” Keep in mind that the syntax used in wikis (i.e. Textile, Markdown, etc.) is not HTML, so basic copy/paste is a no-go. However, you’d think that if there was a way to convert a given HTML page into Textile or Markdown that would get you most of the way there.

Luckily, I found a script that does this pretty well. This script is written in Python and runs on the command line, so you’ll have to be pretty geeky to make use of it. I actually extracted this script from this Mac OS X Service.

You may notices it converts the text to more of a Markdown format. What I’ve done is simply use Instiki as my wiki software of choice, which can be set up to support both Textile and Markdown.

Good luck with your wiki projects.