Class: RedCloth3

Inherits:
String show all
Includes:
Redmine::Helpers::URL
Defined in:
lib/redcloth3.rb

Overview

RedCloth

RedCloth is a Ruby library for converting Textile and/or Markdown into HTML. You can use either format, intermingled or separately. You can also extend RedCloth to honor your own custom text stylings.

RedCloth users are encouraged to use Textile if they are generating HTML and to use Markdown if others will be viewing the plain text.

What is Textile?

Textile is a simple formatting style for text documents, loosely based on some HTML conventions.

Sample Textile Text

h2. This is a title

h3. This is a subhead

This is a bit of paragraph.

bq. This is a blockquote.

Writing Textile

A Textile document consists of paragraphs. Paragraphs can be specially formatted by adding a small instruction to the beginning of the paragraph.

h[n].   Header of size [n].
bq.     Blockquote.
#       Numeric list.
*       Bulleted list.

Quick Phrase Modifiers

Quick phrase modifiers are also included, to allow formatting of small portions of text within a paragraph.

\_emphasis\_
\_\_italicized\_\_
\*strong\*
\*\*bold\*\*
??citation??
-deleted text-
+inserted text+
^superscript^
~subscript~
@code@
%(classname)span%

==notextile== (leave text alone)

To make a hypertext link, put the link text in “quotation marks” followed immediately by a colon and the URL of the link.

Optional: text in (parentheses) following the link text, but before the closing quotation mark, will become a Title attribute for the link, visible as a tool tip when a cursor is above it.

Example:

"This is a link (This is a title) ":http://www.textism.com

Will become:

<a href="http://www.textism.com" title="This is a title">This is a link</a>

Images

To insert an image, put the URL for the image inside exclamation marks.

Optional: text that immediately follows the URL in (parentheses) will be used as the Alt text for the image. Images on the web should always have descriptive Alt text for the benefit of readers using non-graphical browsers.

Optional: place a colon followed by a URL immediately after the closing ! to make the image into a link.

Example:

!http://www.textism.com/common/textist.gif(Textist)!

Will become:

<img src="http://www.textism.com/common/textist.gif" alt="Textist" />

With a link:

!/common/textist.gif(Textist)!:http://textism.com

Will become:

<a href="http://textism.com"><img src="/common/textist.gif" alt="Textist" /></a>

Defining Acronyms

HTML allows authors to define acronyms via the tag. The definition appears as a tool tip when a cursor hovers over the acronym. A crucial aid to clear writing, this should be used at least once for each acronym in documents where they appear.

To quickly define an acronym in Textile, place the full text in (parentheses) immediately following the acronym.

Example:

ACLU(American Civil Liberties Union)

Will become:

<abbr title="American Civil Liberties Union">ACLU</abbr>

Adding Tables

In Textile, simple tables can be added by separating each column by a pipe.

|a|simple|table|row|
|And|Another|table|row|

Attributes are defined by style definitions in parentheses.

table(border:1px solid black).
(background:#ddd;color:red). |{}| | | |

Using RedCloth

RedCloth is simply an extension of the String class, which can handle Textile formatting. Use it like a String and output HTML with its RedCloth#to_html method.

doc = RedCloth.new "

h2. Test document

Just a simple test."

puts doc.to_html

By default, RedCloth uses both Textile and Markdown formatting, with Textile formatting taking precedence. If you want to turn off Markdown formatting, to boost speed and limit the processor:

class RedCloth::Textile.new( str )

Constant Summary

VERSION = 
'3.0.4'
DEFAULT_RULES = 
[:textile, :markdown]

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Redmine::Helpers::URL

#uri_with_safe_scheme?

Methods inherited from String

#is_binary_data?

Methods included from Redmine::CoreExtensions::String::Inflections

#with_leading_slash

Methods included from Redmine::CoreExtensions::String::Conversions

#to_hours

Methods included from Diffable

#diff, #patch, #replacenextlarger, #reverse_hash

Constructor Details

#initialize(string, restrictions = []) ⇒ RedCloth3

Returns a new RedCloth object, based on string and enforcing all the included restrictions.

r = RedCloth.new( "h1. A <b>bold</b> man", [:filter_html] )
r.to_html
  #=>"<h1>A &lt;b&gt;bold&lt;/b&gt; man</h1>"



255
256
257
258
 
# File 'lib/redcloth3.rb', line 255

def initialize( string, restrictions = [] )
    restrictions.each { |r| method( "#{ r }=" ).call( true ) }
    super( string )
end

Instance Attribute Details

#filter_html ⇒ Object

Two accessor for setting security restrictions.

This is a nice thing if you're using RedCloth for formatting in public places (e.g. Wikis) where you don't want users to abuse HTML for bad things.

If :filter_html is set, HTML which wasn't created by the Textile processor will be escaped.

If :filter_styles is set, it will also disable the style markup specifier. ('red')



186
187
188
 
# File 'lib/redcloth3.rb', line 186

def filter_html
  @filter_html
end

#filter_styles ⇒ Object

Two accessor for setting security restrictions.

This is a nice thing if you're using RedCloth for formatting in public places (e.g. Wikis) where you don't want users to abuse HTML for bad things.

If :filter_html is set, HTML which wasn't created by the Textile processor will be escaped.

If :filter_styles is set, it will also disable the style markup specifier. ('red')



186
187
188
 
# File 'lib/redcloth3.rb', line 186

def filter_styles
  @filter_styles
end

#hard_breaks ⇒ Object

Accessor for toggling hard breaks.

If :hard_breaks is set, single newlines will be converted to HTML break tags. This is the default behavior for traditional RedCloth.



195
196
197
 
# File 'lib/redcloth3.rb', line 195

def hard_breaks
  @hard_breaks
end

#lite_mode ⇒ Object

Accessor for toggling lite mode.

In lite mode, block-level rules are ignored. This means that tables, paragraphs, lists, and such aren't available. Only the inline markup for bold, italics, entities and so on.

r = RedCloth.new( "And then? She *fell*!", [:lite_mode] )
r.to_html
#=> "And then? She <strong>fell</strong>!"



207
208
209
 
# File 'lib/redcloth3.rb', line 207

def lite_mode
  @lite_mode
end

#no_span_caps ⇒ Object

Accessor for toggling span caps.

Textile places `span' tags around capitalized words by default, but this wreaks havoc on Wikis. If :no_span_caps is set, this will be suppressed.



217
218
219
 
# File 'lib/redcloth3.rb', line 217

def no_span_caps
  @no_span_caps
end

#rules ⇒ Object

Establishes the markup predence. Available rules include:

Textile Rules

The following textile rules can be set individually. Or add the complete set of rules with the single :textile rule, which supplies the rule set in the following precedence:

refs_textile

Textile references (i.e. [hobix]hobix.com/)

block_textile_table

Textile table block structures

block_textile_lists

Textile list structures

block_textile_prefix

Textile blocks with prefixes (i.e. bq., h2., etc.)

inline_textile_image

Textile inline images

inline_textile_link

Textile inline links

inline_textile_span

Textile inline spans

glyphs_textile

Textile entities (such as em-dashes and smart quotes)

Markdown

refs_markdown

Markdown references (for example: [hobix]: hobix.com/)

block_markdown_setext

Markdown setext headers

block_markdown_atx

Markdown atx headers

block_markdown_rule

Markdown horizontal rules

block_markdown_bq

Markdown blockquotes

block_markdown_lists

Markdown lists

inline_markdown_link

Markdown links



246
247
248
 
# File 'lib/redcloth3.rb', line 246

def rules
  @rules
end

Instance Method Details

#to_html(*rules) ⇒ Object

Generates HTML from the Textile contents.

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



267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/redcloth3.rb', line 267

def to_html( *rules )
    rules = DEFAULT_RULES if rules.empty?
    # make our working copy
    text = self.dup
    
    @urlrefs = {}
    @shelf = []
    textile_rules = [:block_textile_table, :block_textile_lists,
                     :block_textile_prefix, :inline_textile_image, :inline_textile_link,
                     :inline_textile_code, :inline_textile_span, :glyphs_textile]
    markdown_rules = [:refs_markdown, :block_markdown_setext, :block_markdown_atx, :block_markdown_rule,
                      :block_markdown_bq, :block_markdown_lists, 
                      :inline_markdown_reflink, :inline_markdown_link]
    @rules = rules.collect do |rule|
        case rule
        when :markdown
            markdown_rules
        when :textile
            textile_rules
        else
            rule
        end
    end.flatten

    # standard clean up
    incoming_entities text 
    clean_white_space text 

    # start processor
    @pre_list = []
    rip_offtags text
    no_textile text
    escape_html_tags text
    # need to do this before #hard_break and #blocks
    block_textile_quotes text unless @lite_mode
    hard_break text 
    unless @lite_mode
        refs text
        blocks text
    end
    inline text
    smooth_offtags text

    retrieve text

    text.gsub!( /<\/?notextile>/, '' )
    text.gsub!( /x%x%/, '&#38;' )
    clean_html text if filter_html
    text.strip!
    text

end