RedCloth Documentation

To create a custom output format for RedCloth, you should implement a module that includes RedCloth::Formatters::Base. This module provides helper methods for handling phrase transformations, attribute generation, and versioning.

When implementing your formatter, you can use the following lifecycle hooks to manipulate the output:

• before_transform(text): Called before the transformation process begins.
• after_transform(text): Called after the transformation process is complete.

Note that method_missing is implemented to return opts[:text] or an empty string, which allows the parser to gracefully handle unsupported phrase methods in your custom formatter.

To use RedCloth, require the redcloth gem (note the lowercase name). You convert Textile text to HTML by initializing a new RedCloth object with your text and calling the to_html method.

require 'redcloth'

# Simple usage
text = "This is *my* text."
puts RedCloth.new(text).to_html

# Multi-line usage
doc = RedCloth.new <<EOD
h2. Test document

Just a simple test.
EOD
puts doc.to_html

You can install RedCloth using the standard RubyGems command. On most platforms, the C extension will be compiled automatically during installation.

gem install RedCloth

The LaTeX formatter allows mapping CSS style names to LaTeX formatting options for images. This is managed via the latex_image_styles method within the RedCloth::TextileDoc settings. You can define custom styles that will be applied to the \includegraphics command in the generated LaTeX output.

# Note: This is a configuration hook within RedCloth::TextileDoc
# You would typically interact with this by setting values in the doc settings
doc.latex_image_styles['my-style'] = 'width=5cm'

Use the following accessors to control specific Textile parsing behaviors:

• lite_mode: When enabled, block-level rules (tables, paragraphs, lists, etc.) are ignored. Only inline markup like bold and italics is processed.
• no_span_caps: When enabled, suppresses the default behavior where Textile places <span> tags around capitalized words.
• hard_breaks: Toggles whether single newlines are converted to HTML <br> tags. This is enabled by default in current versions.

To prevent users from abusing HTML in public places (like Wikis), you can set several security-related accessors on the RedCloth::TextileDoc instance:

• filter_html: If set, HTML that was not created by the Textile processor will be escaped.
• sanitize_html: If set, HTML can pass through the Textile processor, but unauthorized tags and attributes will be removed.
• filter_styles: Disables the style markup specifier (e.g., {color: red}).
• filter_classes: Disables class attributes (e.g., !(classname)image!).
• filter_ids: Disables id attributes (e.g., !(classname#id)image!).

Use the to_html method to generate HTML from the Textile content. You can optionally pass additional rules as arguments to modify the output during conversion.

RedCloth.new( "And then? She *fell*!" ).to_html
#=> "<p>And then? She <strong>fell</strong>!</p>"

By default, RedCloth does not filter unsafe HTML tags. To prevent XSS or unwanted tags from being rendered, pass the :filter_html option to the constructor.

RedCloth.new("<script>alert(1)</script>", [:filter_html]).to_html
# Returns: "&lt;script&gt;alert(1)&lt;/script&gt;"

RedCloth provides an extension to the ERB::Util module that adds a textilize method. This allows you to transform Textile syntax directly into HTML within ERB templates or any class that includes ERB::Util.

To use it, ensure you have required erb and included ERB::Util in your scope. You can call textilize(string) or its alias t(string) to convert a Textile string to HTML.

require "erb"
include ERB::Util

puts textilize("Isn't ERB *great*?")
# Output: <p>Isn&#8217;t <span class="caps">ERB</span> <strong>great</strong>?</p>

Create a new RedCloth::TextileDoc instance by passing the input string and an optional array of restrictions. When passing restrictions, the corresponding boolean accessors (e.g., filter_html=) are automatically set to true for that instance.

r = RedCloth.new( "h1. A *bold* man", [:lite_mode] )