Acts as Markup¶ ↑

<img src=“https://codeclimate.com/github/vigetlabs/acts_as_markup.png” />

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

GitHub Project: github.com/vigetlabs/acts_as_markup

RDoc:

• 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”, “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:

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 :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:¶ ↑

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_mediawiki:¶ ↑

class Post < ActiveRecord
  acts_as_mediawiki :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_mediawiki :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:

• BlueCloth

• RDiscount

• Ruby PEG

• Maruku

• Redcarpet

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"

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:¶ ↑

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).