Acts as Markup

by Brian Landau of Viget Labs <[email protected]>

GitHub Project: github.com/vigetlabs/acts_as_markup

RDoc:

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”, “mediawiki” 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 5 different types of Markdown processing backends: BlueCloth, RDiscount, Ruby PEG, Redcarpet or Maruku. You specify which one you want to use by setting a config value in your environment.rb file:

ActsAsMarkupOn.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 :mediawiki_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_on`:

class Post < ActiveRecord
  acts_as_markdown_on :body
end

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

Using `acts_as_textile_on`:

class Post < ActiveRecord
  acts_as_textile_on :body
end

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

Using `acts_as_mediawiki_on`:

class Post < ActiveRecord
  acts_as_mediawiki_on :body
end

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

Using `acts_as_rdoc_on`:

class Post < ActiveRecord
  acts_as_rdoc_on :body
end

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

Using `acts_as_markup_on`:

class Post < ActiveRecord
  acts_as_markup_on :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_on :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_on :body, :markdown_options => [ :filter_html ]
end

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

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

REQUIREMENTS:

You will need the RedCloth library for processing the Textile text, and the WikiCloth library for processing mediawiki text.

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

INSTALL:

Rails 2

(sudo) gem install acts_as_markup

Add “acts_as_markup” to your environment.rb:

config.gem "acts_as_markup"

Rails 3

Simply add “acts_as_markup” to your Gemfile:

gem "acts_as_markup"

Rails 4

Simply add “acts_as_markup_on” to your Gemfile:

gem "acts_as_markup_on"

And run “bundle install”

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:

Add another item to the ActsAsMarkupOn::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.
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.
Add appropriate tests (see current tests).

Instructions for how to add a new Markup Language:

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”).
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).
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”).
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
```
Add a convenience method (e.g. “acts_as_markdown”)
Add an extension file to the “lib/acts_as_markup/exts/” directory if you need to modify the object in anyway.
Add appropriate tests (see current tests).