Class: RedCloth3
- Includes:
- Redmine::Helpers::URL
- Defined in:
- lib/redmine/wiki_formatting/textile/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)
Links
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 )
Direct Known Subclasses
Constant Summary collapse
- VERSION =
'3.0.4'
- DEFAULT_RULES =
[:textile, :markdown]
Instance Attribute Summary collapse
-
#filter_html ⇒ Object
Two accessor for setting security restrictions.
-
#filter_styles ⇒ Object
Two accessor for setting security restrictions.
-
#hard_breaks ⇒ Object
Accessor for toggling hard breaks.
-
#lite_mode ⇒ Object
Accessor for toggling lite mode.
-
#no_span_caps ⇒ Object
Accessor for toggling span caps.
-
#rules ⇒ Object
Establishes the markup predence.
Instance Method Summary collapse
-
#initialize(string, restrictions = []) ⇒ RedCloth3
constructor
Returns a new RedCloth object, based on string and enforcing all the included restrictions.
-
#to_html(*rules) ⇒ Object
Generates HTML from the Textile contents.
Methods included from Redmine::Helpers::URL
#uri_with_link_safe_scheme?, #uri_with_safe_scheme?
Methods included from Redmine::StringArrayDiff::Diffable
#diff, #patch, #replacenextlarger, #reverse_hash
Methods included from Redmine::CoreExt::String::Inflections
Methods included from Redmine::CoreExt::String::Conversions
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 <b>bold</b> man</h1>"
257 258 259 260 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 257 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’)
188 189 190 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 188 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’)
188 189 190 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 188 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.
197 198 199 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 197 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>!"
209 210 211 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 209 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.
219 220 221 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 219 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
248 249 250 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 248 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>!"
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 319 320 |
# File 'lib/redmine/wiki_formatting/textile/redcloth3.rb', line 269 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_code, :inline_textile_span, :inline_textile_link, :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 = [] text no_textile text remove_html_comments text 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 text retrieve text text.gsub!(/<\/?notextile>/, '') text.gsub!("x%x%", '&') clean_html text if filter_html text.strip! text end |