Acts as Markup

by Brian Landau of Viget Labs <brian.landau@viget.com>

GitHub Project: github.com/vigetlabs/acts_as_markup

RDoc:

• viget.rubyforge.org/acts_as_markup
• gitrdoc.com/vigetlabs/acts_as_markup/tree/master
• vigetlabs.github.com/acts_as_markup

DESCRIPTION:

Allows you to specify columns of an ActiveRecord model that contain Markdown, Textile, Wiki text and RDoc. You may then use to_s to get the original markup text or to_html to get the formated HTML.

Additionally you can have a model that contains a column that has a column with markup text, and another that defines what language to process it as. If the field is listed as "markdown" "textile", "wikitext" or "rdoc" (case insensitive) it will treat it as such, any other value for markup language will have the value pass through as a normal string.

This AR extension can use 3 different types of Markdown processing backends: BlueCloth, RDiscount, Ruby PEG or Maruku. You specify which one you want to use by setting a config value in your environment.rb file:

    ActsAsMarkup.markdown_library = :bluecloth

By default RDiscount will be used.

You can specify additional options to pass to the markup library by using :markdown_options, :textile_options or :wikitext_options. RDoc does not support any useful options. The options should be given as an array of arguments. You can specify options for multiple languages when allowing more than one. See each library’s documentation for more details on what options are available.

EXAMPLES:

Using acts_as_markdown:

    class Post < ActiveRecord
      acts_as_markdown :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "## Markdown Headline"
    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"

Using acts_as_textile:

    class Post < ActiveRecord
      acts_as_textile :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "h2. Textile Headline"
    @post.body.to_html  #=> "<h2>Textile Headline</h2>"

Using acts_as_wikitext:

    class Post < ActiveRecord
      acts_as_wikitext :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "== Wikitext Headline =="
    @post.body.to_html  #=> "<h2>Wikitext Headline</h2>"

Using acts_as_rdoc:

    class Post < ActiveRecord
      acts_as_rdoc :body
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "== RDoc Headline"
    @post.body.to_html  #=> "<h2>RDoc Headline</h2>"

Using acts_as_markup:

    class Post < ActiveRecord
      acts_as_markup :language => :markdown, :columns => [:body]
    end

    @post = Post.find(:first)
    @post.body.to_s     #=> "## Markdown Headline"
    @post.body.to_html  #=> "<h2> Markdown Headline</h2>"

Using acts_as_markup with :variable language:

    class Post < ActiveRecord
      acts_as_markup :language => :variable, :columns => [:body]
    end

    @post = Post.find(:first)
    @post.markup_language      # => "markdown"
    @post.body.to_s            # => "## Markdown Headline"
    @post.body.to_html         # => "<h2> Markdown Headline</h2>"

Using options

    class Post < ActiveRecord
      acts_as_markdown :body, :markdown_options => [ :filter_html ]
    end

    class Post < ActiveRecord
      acts_as_textile :body, :textile_options => [ [ :filter_html ] ]
    end

    class Post < ActiveRecord
      acts_as_wikitext :body, :wikitext_options => [ { :space_to_underscore => true } ]
    end

REQUIREMENTS:

You will need the RedCloth library for processing the Textile text, and the Wikitext library for processing wikitext.

You will also need to install some type of Markdown processor. The three options currently supported are:

• BlueCloth
• RDiscount
• Ruby PEG
• Maruku

INSTALL:

sudo gem install acts_as_markup

Add "acts_as_markup" to your environment.rb:

    config.gem "acts_as_markup"

CONTRIBUTING:

Make a fork on GitHub, make your changes and do a pull request. Good places to start are adding new Markdown libraries or new markup languages, here’s instructions for both:

Instructions for how to add a new Markdown Library:

1. Add another item to the ActsAsMarkup::MARKDOWN_LIBS hash in the form of:

       :bluecloth => {:class_name => "BlueCloth",
                      :lib_name   => "bluecloth"}
   

   :lib_name should be the name needed to require the library, while :class_name should be the class that we are making an instance of.

2. If you need to modify the object in anyway (e.g. to add a to_s or to_html method), add a file to the "lib/acts_as_markup/exts/" directory.
3. Add appropriate tests (see current tests).

Instructions for how to add a new Markup Language:

1. Add a "when" statement to the "case" statement in acts_as_markup. The "when" statement should match with a symbol that represents the language name in some way (e.g. ":markdown").
2. In the "when" block you need to set the "klass" local variable and require the library and the extension file if you need one (use the special require_extensions method to require extensions).
3. Add the same lines you added to the previous "when" statement to the ":variable" "when" statement. But replace "klass" with "language_klass" (e.g. "markdown_klass").
4. Add a relevant "when" statement to the class_eval block for the ":variable" language option. This should look something like:

       when /markdown/i
         markup_klasses[:markdown].new self[col].to_s
   

5. Add a convenience method (e.g. "acts_as_markdown")
6. Add an extension file to the "lib/acts_as_markup/exts/" directory if you need to modify the object in anyway.
7. Add appropriate tests (see current tests).