Markdown on Rails

A Ruby on Rails template handler for the markdown format.

Licence

Markdown on Rails is released under the MIT licence.

Download / Install

The code can be downloaded from the subversion repository: svn://rubygreenblue.com/rubygreenblue_opensource/markdown_on_rails/trunk

  • install as a gem

    sudo gem install markdown_on_rails-0.0.x.gem

  • install as a plugin

    script/plugin install svn://rubygreenblue.com/rubygreenblue_opensource/markdown_on_rails/trunk

Usage

It is very straight forward to use:

in your config/environment.rb file:

require 'markdown_on_rails'
ActionView::Base.register_template_handler('text', MarkdownOnRails)
MarkdownOnRails::map_headings_down_by 0

The MarkdownOnRails::map_headings_down_by 0 tells the handler to map headings by n. For example, if you set MarkdownOnRails::map_headings_down_by 2 and write a document like:

# First Heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

## Second Heading

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

The resulting html will feature <h3> and <h4> for the two headings respectively.

If you have MarkdownOnRails::map_headings_down_by 0, no mapping of headings takes place and you would get <h1> and <h2>.

This feature is there so you can always write your documents starting with a first level heading and then if you include the document in two different places that happen to require headings for content to start at something other than a first level heading, you can do so without having to change your content.

The only other thing left to do is to create your views as .text files and use markdown syntax.

ERB is available inside the .text files if you are using it as a rails view (as for normal '.rhtml' views). eg:

# Thank you

Thanks <%= @username %> for...

Credit

I gladly give credit to John Gruber of daringfireball.net for creating markdown - it has made my professional life much more fun.

I also give credit to Michael Granger for porting John Gruber's code to Ruby in the form of Bluecloth. My code obviously depends heavily (critically) on Bluecloth. Using Bluecloth means the amount of code I had to write is embarrassingly little, and for that embarrassment I give credit to the Ruby language.