Frequently Asked Questions

What do I need to run RedCloth?

If you want to just use RedCloth—that is, put in Textile and have it output HTML or LaTeX—you don’t need anything. RedCloth has no dependencies1.

RedCloth can be installed via RubyGems:

gem install RedCloth

It will install the appropriate Ruby, JRuby, or Win32 gem. If using JRuby, version 1.1.5 or greater is required.

1 RubyGems < 1.3 had a problem with some older versions of RedCloth that required echoe as a development dependency, but that’s all cleared up now.

What do I need to hack on RedCloth?

To fix bugs, add features, or otherwise hack on RedCloth, you’ll need Ragel 6.3 or later, which can be installed using your system’s package manager (macports, apt, RPM). Then:

  1. gem install bundler
  2. bundle install

That will install all the dependencies needed for hacking on RedCloth. To compile, you just rake compile.

To compile/cross-compile all the gems for a release (MRI, JRuby, mingw, and win32 gems), you need rvm and rake-compiler.

  1. gem install bundler
  2. bundle install
  3. rake-compiler cross-ruby VERSION=1.8.6-p398
  4. rake-compiler cross-ruby VERSION=1.9.1-p243
  5. rake build:all

N.B.: You don’t have to compile RedCloth if you just want to run RedCloth or if you want a custom formatter or extension. I sometimes hear people grumbling about having to install Ragel just to use or customize RedCloth. You don’t. You only have to compile RedCloth from its Ragel sources if you’re hacking on the Ragel code.

How do I customize RedCloth?

Most customizations fall into a couple categories:

Custom output

If you want to change the HTML or LaTeX that is output, all you have to do is override the appropriate method in the formatter.

=> "<p style=\"float:left;\"><img src=\"logo.jpg\" alt=\"\" /></p>"
>> module RedCloth::Formatters::HTML
>>   def p(opts)
>>     float = opts.delete(:float)
>>     opts[:class] = "float-#{float}"
>>     "<p#{pba(opts)}>#{opts[:text]}</p>\n"
>>   end
>> end
=> nil
=> "<p class=\"float-left\"><img src=\"logo.jpg\" alt=\"\" /></p>"

Or, if you wish, you can create a new formatter module that inherits from one of the existing ones (so you can use super). Then, instead of calling to_html, call to(RedCloth::Formatters::YourCustomModule).

Custom input patterns

Custom blocks can be detected by extending the formatter with the method name of the block you want to recognize. For an example, see spec/custom_tags_spec.rb

Other custom input patterns, such as wiki links, can efficiently be pre-processed by gsubbing the text before handing it to RedCloth. For an example, see spec/extension_spec.rb There are also #before_transform and #after_transform hooks in the formatters you can tap into.

Custom formatters

HTML and LaTeX not doing it for you? Need to convert Textile to plain text, BBCode, Apple-QuickView, etc.? Build a new formatter that outputs the format you want.

Why doesn't RedCloth do Markdown?

Because Textile is infinitely superior! Just kidding. There are good uses for each. Markdown is great for plain text documents that are to be read as plain text and might be converted to HTML, but Textile works better for me as a shortcut to HTML (not published plain-text). I have my reasons for preferring Textile but I can see both sides.

RedCloth started out as a Textile parser. Along the way, Markdown support was added and as a result, RedCloth suffered for several years. There were clashes between the two formats—not the least of which was the way line breaks were handled—and it added so much complexity that RedCloth gained a reputation for being buggy and slow.

RedCloth 4 was a total rewrite that brought it back to its Textile roots, fixed a lot of bugs, and made it roughly 40x faster.

There are other libraries out there that parse Markdown, BBCode, or whatever, so there’s no reason to reinvent the wheel. Most sites let you specify the text format you’re using. Seems we’ve learned the hard way that mixing formats in the same document is a recipe for disaster. What would be interesting is a library that detects the format of the document and automatically switches parsers.

Why am I getting extra leading spaces? It's messing up my code blocks!

So, you’re getting 12 extra spaces before each line? It’s probably not RedCloth’s fault. It has no indentation other than some tab characters to indent lists. Are you using HAML? That will automatically indent things unless you tell it not to. Better yet, HAML has built-in support for the Textile filter, which uses RedCloth behind the scenes.

What's up with hard breaks?

In Textile, two newline characters (made with the return key) start a new paragraph. Just one makes a line break or “hard break” (<br /> in HTML). Think poetry and addresses.

In the original PHP version of Textile and for the first several versions of RedCloth, this was always the case. Then the author tried to mix in Markdown formatting and disabled hard breaks. Chaos ensued. Textile documents worked one way on one site and another way on another site depending on the version of RedCloth and whether the developer had passed in the :hard_breaks option. Google a bit and you’ll see what confusion and frustration it created. Thankfully, Ruby on Rails’ textilize helper always kept :hard_breaks on, maintaining a modicum of consistency.

RedCloth 4 removed Markdown and made hard breaks once again the default (thus making the option redundant). There’s still a hard_breaks accessor if you absolutely must. If you feel so strongly that the parser should ignore line breaks, perhaps you should consider using Markdown!