Using a different Markdown processor

There are a handful of Markdown processing libraries available for Ruby, each with different advantages and features. Since version 0.9.11, Nesta uses Ryan Tomayko's Tilt library to work out which processor to use when rendering a file within your content folder.

At the time of writing, Tilt knows about the following Markdown processors:

Tilt will try to load a Markdown processor in the order defined above. If it can't find Redcarpet, it'll try RDiscount, then BlueCloth, etc.

RDiscount is used in Nesta by default, as it is the only one that is included automatically as a Nesta dependency (i.e. it is the only one that is likely to be available in your project so Tilt is likely to find it first).

Installing other processors

To change the default (e.g. to BlueCloth), add your chosen processor's gem to your Gemfile and re-run bundle:

$ cd path/to/project
$ echo 'gem "bluecloth"' >> Gemfile
$ bundle

The other gems that you might want to install are called redcarpet, kramdown and maruku (the rdiscount gem is already installed).

Configuring Tilt

Then tell Tilt that you'd rather it used BlueCloth by adding the following line of Ruby code to the app.rb file within your project (if you don't have an app.rb file, just create it):

Tilt.register Tilt::BlueClothTemplate, 'md'

The full list of class names that you might want to use in place of BlueClothTemplate is:

  • Tilt::RedcarpetTemplate
  • Tilt::RDiscountTemplate
  • Tilt::BlueClothTemplate
  • Tilt::KramdownTemplate
  • Tilt::MarukuTemplate

This post may go out of date as the Markdown processing support in Ruby evolves. You can always check the list of class names at the bottom of tilt.rb to review current options…

Graham Ashton is the author and maintainer of Nesta CMS. He lives in Manchester where he's building a simpler app for tracking agile projects.

He writes a technical blog at http://effectif.com and can be found at @grahamashton on Twitter.