rubybook = :title => “Gerald Bauer’s Ruby Notebook”, :about => “Internet Professional in Vancouver, B.C.”

Gerald Bauer’s Ruby Notebook

RedCloth Cookbook: How Tos, Recipes, F.A.Qs - Using the Ruby Plain Text to Web Markup Gem

leave a comment »

What’s Textile? What’s RedCloth?

Textile is a wiki-style markup language that’s easy-to-write and easy-to-read and that lets you author web pages in plain text. RedCloth is the Ruby gem that lets you use Textile in Ruby.

Using RedCloth

The RedCloth class is an extension of Ruby’s String class. Use it like you use a String:

>> doc = "*strong words* and _emphasized words_"
=> "*strong words* and _emphasized words_"

To generate web markup (HTML) from your RedCloth object, use the RedCloth#to_html method:

>> doc.to_html
=> "<p><strong>strong words</strong> and <em>emphasized words</em></p>"

That’s it. Now on to the RedCloth Cookbook and the How Tos and Recipes.

How to use the redcloth command line tool

Once you have the RedCloth gem installed you get a command line tool for free. Try:

$ redcloth -h

Printing out:

>> Usage: redcloth [options] [redcloth_formatted.txt]
>> If no file specified, STDIN will be used. If you are typing input,
>>   you can send an EOF by pressing ^D (^Z on Windows)
>>   -o, --output STYLE               Output format (defaults to html)

For example to create this page use:

$ redcloth redcloth.textile > redcloth.html

How to turn off/disable hard line breaks

Traditional Textile and RedCloth (starting with version 4.0 and up) convert single newlines to break tags (<br>) in web markup e.g.:

>> "some text\nsome more text\nand some more\n" ).to_html

Results in:

=> "<p>some text<br />\nsome more text<br />\nand some more</p>"

If you want to turn off/disable hard line breaks use:

>> doc = "some text\nsome more text\nand some more\n"  )
>> doc.hard_breaks = false
>> doc.to_html

Resulting in:

=> "<p>some text\nsome more text\nand some more</p>"

How to turn off span caps

Textile wraps <span> tags around capitalized words by default e.g.:

>> "some acronyms/all-cap words: HTTP, HTML, URI" ).to_html

Results in:

=> "<p>some acronyms/all-cap words: <span class=\"caps\">HTTP</span>,
<span class=\"caps\">HTML</span>, <span class=\"caps\">URI</span></p>"

If you want to turn off span caps use:

>> "some acronyms/all-cap words: HTTP, HTML, URI", [:no_span_caps] ).to_html

Resulting in:

=> "<p>some acronyms/all-cap words: HTTP, HTML, URI</p>"

How to extend Textile with your own rules

See the Smiley Extension Test Case.

How to extend Textile with your own tags

See the Figure Custom Tag Test Case.


Official References:

Questions, comments, corrections, updates? Send them along to the RedCloth mailing list or the Vancouver.rb mailing/forum. Thanks!

Written by Gerald

August 16, 2008 at 6:15 am

Comments are closed.