BBRedCloth – BBCode/Textile parser for Ruby

Homepage:: http://redcloth.org
Authors:: Jason Garber
Ryan Alyea
Copyright:: © 2008 Jason Garber
© 2009 Ryan Alyea
License:: MIT

(See http://redcloth.org/textile/ for a Textile reference.)

Latest Updates

Holy crap, it’s 2021?

• Updated version to 0.9.0.alpha1. The minor version bump is due to minor breaking changes listed below.
• Cherry-picked every major update from RedCloth until this post, which RedCloth has not been updated since 2018. (Nothing wrong with that. Don’t fix what ain’t broke.) I did not port the RSpec, gem-building, or other new meta elements. But the base engine is still the same so there’s no need because the gem-building at least originally was for building on Windows and Java which BBRedCloth does not support.
• Includes CVE-2012-6684. Although I highly, highly recommend using an html sanitizer on top of this because Textile lets you some EVIL things in CSS.
• YouTube and Vimeo support was removed. It used the super old flash version anyway.
• Removed the swear filter, it wasn’t perfect.
• All tests pass. NOTE: Malformed BBCode currently produces non-ideal but valid and secure HTML code. Don’t mess up your BBCode and it’s all fine.
• Confirmed working on Ruby 3.0.0
• If you are using BBRedCloth, simply including the pre-packaged gem file is fine. Due to the reliance on Ragel, you cannot just include a Github project.
  • Since I have not yet ported the build system, you need the last version of echoe gem and Ruby 1.9.3 to actually build the gem using rake package. Sorry, not sorry. You can still build Ruby 1.9.3 on macOS Big Sur if you remove or use the super insecure old OpenSSL 1.0.2t, so it’s not like super-hard.
  • Once you have the .gem file, later version of Ruby such as 3.0.0 can then build the native extension normally like any gem.

BBRedCloth

BBRedCloth is a Ruby library for converting Textile into HTML. While fundamentally based on RedCloth, it also contains the ability to convert standard “BBCode” also, which is useful for forums which use this style of markup since, well… forever. As a drop-in replacement for RedCloth, it plays well such that Textile and BBCode can work side-by-side without much effort for the implementer.

Installing

RedCloth can be installed via RubyGems:

gem install BBRedCloth

It will install the appropriate Ruby gem. JRuby is not supported, nor is the pure-Ruby version.

If you wish to use BBRedCloth in your Rails 3 project, just add the following to your Gemfile:

gem 'BBRedCloth', require:'redcloth'

== Compiling

If you just want to use BBRedCloth, you do NOT need to build/compile it. It is compiled from C sources automatically when you install the gem on the ruby platform.

BBRedCloth can be compiled with rake compile. Ragel 6.3 or greater and the echoe gem (3.1.1) are needed to build, compile, and package RedCloth. Again, Ragel and echoe are NOT needed to simply use RedCloth.

== Using BBRedCloth

BBRedCloth was designed to be mostly drop-in compatible with RedCloth. In fact, it still retains the RedCloth class. However, this makes running BBRedCloth and a newer RedCloth impossible for now.

If you wish to use the general RedCloth/Textile mode with this gem, just do as you normally do!

require 'rubygems'
gem 'BBRedCloth'
require 'RedCloth'
text = "This is *my* text."
RedCloth.new(text).to_html
#=> "<p>This is <strong>my</strong> text.</p>"

BBCode

Because of the drop-in feature, new features must be activated. Just put options in an array after the text. For example:

require 'rubygems'
gem 'BBRedCloth'
require 'RedCloth'
text = "This is *Textile* and [b]BBCode[/b] combined!"
RedCloth.new(text,[:bbcode]).to_html
#=> "<p>This is <strong>Textile</strong> and <strong>BBCode</strong> combined!</p>"

Filters

Most of RedCloth’s options are supported such as :filter_html :

require 'rubygems'
gem 'BBRedCloth'
require 'RedCloth'
text = "This *Textile* and [b]BBCode[/b] and <b>HTML</b> combined!"
RedCloth.new(text,[:bbcode]).to_html
RedCloth.new(text,[:filter_html,:bbcode]).to_html
#=> "<p>This <strong>Textile</strong> and <strong>BBCode</strong> and <b>HTML</b> combined!</p>"
#=> "<p>This <strong>Textile</strong> and <strong>BBCode</strong> and &lt;b&gt;HTML&lt;/b&gt; combined!</p>"

Disabling Certain HTML Code

Additionally, you can disable certain HTML features of BBCode and Textile and they are ignored:

require 'rubygems'
gem 'BBRedCloth'
require 'RedCloth'
RedCloth.new( "Images should *not* be allowed! !test_image.jpg!", [:disable_inline=>:image] ).to_html
#=> "<p>Images should <strong>not</strong> be allowed! !test_image.jpg!</p>"

You can disable the following:

• :image
• :link
• :code
• :notextile
• :strong
• :b
• :em
• :i
• :del
• :ins
• :sup
• :sub
• :span
• :cite
• :snip
• :quote1
• :quote2
• :multi_paragraph_quote
• :link_alias
• :noparagraph_line_start (ie. spaces at the beginning of a paragraph do not render

  tags.)

BBCode-Only

If you want to disable Textile, there is a BBCode-only mode:

require 'rubygems'
gem 'BBRedCloth'
require 'RedCloth'
text = "This is *Textile* and [b]BBCode[/b] combined!"
RedCloth.new(text,[:bbcode_only]).to_html
#=> "<p>This is *Textile* and <strong>BBCode</strong> combined!</p>"

BBCode

The following are the tags supported:

• [b]
• [i]
• [u]
• [s]
• [ins]
• [del]
• [sup]
• [sub]
• [notextile]
• [color]
• [size]
• [align]
• [acronym]
• [url]
• [img]
• [pre]
• [quote]
• [spoiler]