hoodwink.d enhanced
RSS
2.0
XHTML
1.0

RedHanded

Using RedCloth 3 #

by why in inspect

Yeah, I get a lot of e-mail about problems with RedCloth. I think the main problem is that I’ve neglected to explain things. I’ve only just recently update the documentation and it can be a bit much to sort through. Especially when you really only need to know a couple of things about RedCloth 3.

Getting Textile and Markdown to Hold Hands

RedCloth 3 supports both Textile and Markdown. Well, there’s a few Markdown items that haven’t been implemented. I believe lists, backticked code fragments, and images still need to be finished.

By default, these are supported in tandem, with preference given to Textile markup. This is only because RedCloth is historically a Textile library.

However, preference can be given to Markdown.

  RedCloth::DEFAULT_RULES.replace [:markdown, :textile]

You can also use only one of the processors, if you prefer.

This can also be done when you go to output:

 >> r = RedCloth( <<RED ).to_html
 >> # testing
 >> RED
 => "<ol>\n\t<li>testing</li>\n\t</ol>" 

 >> r = RedCloth( <<RED ).to_html( :markdown )
 >> # testing
 >> RED
 => "<h1>testing</h1>" 

Furthermore, you can mix-and-match rules from either processor to form your own custom markups.

 >> r = RedCloth( <<RED ).to_html \
 ?>       :block_markdown_atx, :inline_textile_link 
The complete list of rules is available in the RDoc for the RedCloth#rules accessor.

Line Breaking with a Sledgehammer

Since RedCloth 3 supports both Textile and Markdown, there’s a bit of clash in some subtle rules. For example, the string 4 > 5 is handled differently.

Textile outputs <p>4 > 5</p>.

Markdown outputs <p>4 &gt; 5</p>.

Generally, I side with Textile on these subtelties. Eventually, I hope that these behaviors can be placed in rules like the above. But I end up sort of stumbling across them inadvertantly, you know?

With line breaks, I decided to side with Markdown. I got so many complaints with line breaks converting to <br /> tags in RedCloth 2. People just didn’t expect it.

Heh, well, now people are used to it and they’re pretty disoriented using RedCloth 3! Anyway, this is an easy one.

 class RedCloth
   def hard_breaks; true; end
 end

This will activate classic hard-breaking globally, like in the days of RedCloth 2’s salad days.

Again, can be done on a per-document basis.

 >> RedCloth.new( <<RED ).to_html
 >> A short little paragraph
 >> of no consequence whatsoever.
 >> RED
 #=> <p>A short, little paragraph
     of no consequence whatsoever.</p>

 >> RedCloth.new( <<RED, [:hard_breaks] ).to_html
 >> A short little paragraph
 >> of no consequence whatsoever.
 >> RED
 #=> <p>A short, little paragraph<br />
     of no consequence whatsoever.</p>

And, hey, I’m just doin what one guy thinks is best. If this stuff drives you nuts, I’m open to a reversal.

Adding Yer Custom Blocks

Everyone’s always asking for custom markup. The most common form being additional Textile prefixes.

Yo, that’s easy!!

 class CustomRedCloth < RedCloth
   def textile_code( tag, atts, cite, content )
     "\t<pre><code#{ atts }>#{ content }</code></pre>" 
   end
 end

Creating textile block prefixes is simply a matter of adding a textile_#{ prefix } method. We now have a code tag.

 >> CustomRedCloth.new( <<RED ).to_html
 >> code. # testing
 >>   a = 1
 >>   b = 2
 >>   c = 3
 >> RED
 
 => <pre><code># testing
      a = 1
      b = 2
      c = 3</code></pre>
 

You can add your own markup rules as well, but it gets a bit more complicated and I’d encourage reading the source. It’s a matter of adding a method and a rule of the same name. Take a look at the block_markdown_setext or block_textile_prefix. Short six- or seven-line methods for adding more complex markup.

said on 18 Feb 2005 at 15:49

Thanks for the write-up. One note: If you’re going to continue to post blog entries about HTML markup, I’d recommend you add Atom support. RSS escaping of this stuff is wildly inconsistent. When I read this in NetNewsWire Lite, all the markup disappeared.

said on 18 Feb 2005 at 15:54

Thanks, _why. I haven’t yet used RedCloth, but I may look at it more in depth as I continue with PDF ::Writer, because I’m looking to simply the markup that is supported by default. The only thing that I disagree with you on stated above is that, when writing to HTML , > should be converted to &gt; as Markdown does it—otherwise, it’s not likely to be a valid XHTML document that’s output.

said on 18 Feb 2005 at 15:58

Yeah, like I said, these subtleties just need to be identified and decided upon. I was just looking at that example today and, I agree with you, I should definitely side with XHTML compliance before anything else.

said on 18 Feb 2005 at 18:19

I’m in strong favor of defaulting to hard breaks. So strong that I just added your fix to Rails’ textilize method so it’ll do so by default.

said on 18 Feb 2005 at 19:04

Hi why,

when :filter_html is set, causes an error (!) and so does !img_url!

Do you know why, _why?

said on 18 Feb 2005 at 19:07

By the way, the missing tag above is the “img src” tag.

I tried it here in the comments, and i’m getting a 500 Internal Server Error.

Hmmm….

said on 18 Feb 2005 at 19:57

I confess I don’t get why people use br tags at all. A linebreak in most markup languages pretty much indicates a paragraph break, and with CSS styling, why is there the need to rely on br for formatting?

I guess making it configurable makes everyone happy though.

said on 27 Oct 2005 at 06:01

def BlogEntriesController.redcloth r = RedCloth.new(“And then? RAGING She fell!” , [:filter_html]) return r.to_html end def BlogEntriesController.redcloth2 r = RedCloth.new( “h1. A italic man”, [:filter_html] ) r.to_html end

neither of these remove the html , the first renders partially bold the second renders italic although in this post because you are using some text formatting you cant see my or tags. You see I thought should be removed / ignored using :filter_html ??? isnt it

Comments are closed for this entry.