Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 517 lines (360 sloc) 15.054 kb
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
1 Tilt Templates
2 ==============
f7bcad2 @rtomayko starting in on template engine docs
authored
3
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
4 (See <https://github.com/rtomayko/tilt/blob/master/TEMPLATES.md> for a rendered,
5 HTML-version of this file).
6
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
7 While all Tilt templates use the same basic interface for template loading and
8 evaluation, each varies in its capabilities and available options. Detailed
9 documentation on each supported template engine is provided below.
10
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
11 There are also some file extensions that have several implementations
12 (currently ERB and Markdown). These template classes have certain features
13 which are guaranteed to work across all the implementations. If you wish to be
14 compatible with all of these template classes, you should only depend on the
15 cross-implementation features.
16
17 * [ERB](#erb) - Generic ERB implementation (backed by erb.rb or Erubis)
18 * [erb.rb](#erbrb) - `Tilt::ERBTemplate`
5d7b643 @rtomayko tidy up TEMPLATES documentation a bit
authored
19 * [Erubis](#erubis) - `Tilt::ErubisTemplate`
20 * [Haml](#haml) - `Tilt::HamlTemplate`
4eeaac4 @rtomayko add basic liquid docs
authored
21 * [Liquid](#liquid) - `Tilt::LiquidTemplate`
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
22 * Nokogiri - `Tilt::NokogiriTemplate`
23 * Builder - `Tilt::BuilderTemplate`
24 * Markaby - `Tilt::MarkabyTemplate`
25 * [Radius](#radius) - `Tilt::RadiusTemplate`
719b0c0 @rtomayko more whitespace errors benschwarz tsk tsk
authored
26
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
27 Tilt also includes support for CSS processors like [LessCSS][lesscss] and
28 [Sass][sass], [CoffeeScript][coffee-script] and some simple text formats.
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
29
7c28004 @benschwarz Did my homework for Mr Tomayko, the geography teacher.
benschwarz authored
30 * Less - `Tilt::LessTemplate`
31 * Sass - `Tilt::SassTemplate`
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
32 * Scss - `Tilt::ScssTemplate`
33 * CoffeeScript - `Tilt::CoffeeScriptTemplate`
34 * [Textile](#redcloth) - `Tilt::RedClothTemplate`
35 * Creole - `Tilt::CreoleTemplate`
23a141b @rtomayko RDocTemplate specs and docs
authored
36 * [RDoc](#rdoc) - `Tilt::RDocTemplate`
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
37
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
38 Tilt has extensive support for Markdown, backed by one of four different
39 implementations (depending on which are available on your system):
40
41 * [Markdown](#markdown) - Generic Markdown implementation
42 * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
ad1d9f7 @rkh add Redcarpet to template docs
rkh authored
43 * Redcarpet - `Tilt::RedcarpetTemplate`
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
44 * BlueCloth - `Tilt::BlueClothTemplate`
45 * Kramdown - `Tilt::KramdownTemplate`
46 * Maruku - `Tilt::MarukuTemplate`
47
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
48 <a name='erb'></a>
f7bcad2 @rtomayko starting in on template engine docs
authored
49 ERB (`erb`, `rhtml`)
50 --------------------
51
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
52 ERB is a simple but powerful template languge for Ruby. In Tilt it's backed by
53 [Erubis](#erubis) (if installed on your system) or by [erb.rb](#erbrb) (which
54 is included in Ruby's standard library). This documentation applies to both
55 implementations.
f7bcad2 @rtomayko starting in on template engine docs
authored
56
57 ### Example
58
59 Hello <%= world %>!
3922e7d Remove whitespace [Gun.io WhitespaceBot]
Gun.io Whitespace Robot authored
60
f7bcad2 @rtomayko starting in on template engine docs
authored
61 ### Usage
62
b52ddae @judofyr Add documentation for fallback mode
judofyr authored
63 ERB templates support custom evaluation scopes and locals:
f7bcad2 @rtomayko starting in on template engine docs
authored
64
65 >> require 'erb'
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
66 >> template = Tilt.new('hello.html.erb')
f7bcad2 @rtomayko starting in on template engine docs
authored
67 >> template.render(self, :world => 'World!')
68 => "Hello World!"
69
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
70 Or, use `Tilt['erb']` directly to process strings:
f7bcad2 @rtomayko starting in on template engine docs
authored
71
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
72 template = Tilt['erb'].new { "Hello <%= world %>!" }
f7bcad2 @rtomayko starting in on template engine docs
authored
73 template.render(self, :world => 'World!')
74
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
75 ### Options
76
77 #### `:trim => trim`
78
79 Omits newlines and spaces around certain lines (usually those that starts with
80 `<%` and ends with `%>`). There isn't a specification for how trimming in ERB
81 should work, so if you need more control over the whitespace, you should use
82 [erb.rb](#erbrb) or [Erubis](#erubis) directly.
83
84
85 #### `:outvar => '_erbout'`
86
87 The name of the variable used to accumulate template output. This can be
88 any valid Ruby expression but must be assignable. By default a local
89 variable named `_erbout` is used.
90
91 <a name='erbrb'></a>
92 erb.rb (`erb`, `rhtml`)
93 -----------------------
94
95 [ERB](#erb) implementation available in Ruby's standard library.
96
97 All the documentation of [ERB](#erb) applies in addition to the following:
98
99 ### Usage
100
101 The `Tilt::ERBTemplate` class is registered for all files ending in `.erb` or
102 `.rhtml` by default, but with a *lower* priority than ErubisTemplate. If you
103 specifically want to use ERB, it's recommended to use `#prefer`:
104
105 Tilt.prefer Tilt::ERBTemplate
106
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
107 __NOTE:__ It's suggested that your program `require 'erb'` at load time when
108 using this template engine within a threaded environment.
109
f7bcad2 @rtomayko starting in on template engine docs
authored
110 ### Options
111
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
112 #### `:trim => true`
f7bcad2 @rtomayko starting in on template engine docs
authored
113
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
114 The ERB trim mode flags. This is a string consisting of any combination of the
115 following characters:
f7bcad2 @rtomayko starting in on template engine docs
authored
116
117 * `'>'` omits newlines for lines ending in `>`
118 * `'<>'` omits newlines for lines starting with `<%` and ending in `%>`
119 * `'%'` enables processing of lines beginning with `%`
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
120 * `true` is an alias of `<>`
f7bcad2 @rtomayko starting in on template engine docs
authored
121
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
122 #### `:safe => nil`
f7bcad2 @rtomayko starting in on template engine docs
authored
123
124 The `$SAFE` level; when set, ERB code will be run in a
125 separate thread with `$SAFE` set to the provided level.
126
e1ce6da @rtomayko document ERB/Erubis :outvar option
authored
127 #### `:outvar => '_erbout'`
128
129 The name of the variable used to accumulate template output. This can be
130 any valid Ruby expression but must be assignable. By default a local
131 variable named `_erbout` is used.
132
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
133 ### See also
134
135 * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
136
137
138 <a name='erubis'></a>
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
139 Erubis (`erb`, `rhtml`, `erubis`)
140 ---------------------------------
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
141
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
142 [Erubis][erubis] is a fast, secure, and very extensible implementation of [ERB](#erb).
143
144 All the documentation of [ERB](#erb) applies in addition to the following:
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
145
146 ### Usage
147
b52ddae @judofyr Add documentation for fallback mode
judofyr authored
148 The `Tilt::ErubisTemplate` class is registered for all files ending in `.erb` or
149 `.rhtml` by default, but with a *higher* priority than `ERBTemplate`. If you
150 specifically want to use Erubis, it's recommended to use `#prefer`:
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
151
b52ddae @judofyr Add documentation for fallback mode
judofyr authored
152 Tilt.prefer Tilt::ErubisTemplate
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
153
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
154 __NOTE:__ It's suggested that your program `require 'erubis'` at load time when
155 using this template engine within a threaded environment.
156
e9782ef @wbzyl added Options section to Erubis
wbzyl authored
157 ### Options
158
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
159 #### `:engine_class => Erubis::Eruby`
e9782ef @wbzyl added Options section to Erubis
wbzyl authored
160
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
161 Allows you to specify a custom engine class to use instead of the
162 default which is `Erubis::Eruby`.
e9782ef @wbzyl added Options section to Erubis
wbzyl authored
163
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
164 #### `:escape_html => false`
e9782ef @wbzyl added Options section to Erubis
wbzyl authored
165
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
166 When `true`, `Erubis::EscapedEruby` will be used as the engine class
167 instead of the default. All content within `<%= %>` blocks will be
168 automatically html escaped.
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
169
e1ce6da @rtomayko document ERB/Erubis :outvar option
authored
170 #### `:outvar => '_erbout'`
171
172 The name of the variable used to accumulate template output. This can be
173 any valid Ruby expression but must be assignable. By default a local
174 variable named `_erbout` is used.
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
175
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
176 #### `:pattern => '<% %>'`
177
178 Set pattern for embedded Ruby code.
179
180 #### `:trim => true`
181
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
182 Delete spaces around `<% %>`. (But, spaces around `<%= %>` are preserved.)
4ee7afa @rtomayko document new erubis options in TEMPLATES.md
authored
183
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
184 ### See also
185
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
186 * [Erubis Home][erubis]
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
187 * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
188
189
190 <a name='haml'></a>
191 Haml (`haml`)
192 -------------
193
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
194 [Haml][haml] is a markup language that’s used to cleanly and simply describe
195 the HTML of any web document without the use of inline code. Haml functions as
196 a replacement for inline page templating systems such as PHP, ASP, and ERB, the
197 templating language used in most Ruby on Rails applications. However, Haml
198 avoids the need for explicitly coding HTML into the template, because it itself
199 is a description of the HTML, with some code to generate dynamic content.
3fbde0d @mattwildig Update links to Haml site
mattwildig authored
200 ([more](http://haml.info/about.html))
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
201
202
203 ### Example
204
205 %html
206 %head
207 %title= @title
208 %body
209 %h1
210 Hello
211 = world + '!'
212
213 ### Usage
214
215 The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
216 by default. Haml templates support custom evaluation scopes and locals:
217
218 >> require 'haml'
219 >> template = Tilt.new('hello.haml')
220 => #<Tilt::HamlTemplate @file='hello.haml'>
221 >> @title = "Hello Haml!"
222 >> template.render(self, :world => 'Haml!')
223 => "
224 <html>
225 <head>
226 <title>Hello Haml!</title>
227 </head>
228 <body>
229 <h1>Hello Haml!</h1>
230 </body>
231 </html>"
232
233 Or, use the `Tilt::HamlTemplate` class directly to process strings:
234
235 >> require 'haml'
236 >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
237 => #<Tilt::HamlTemplate @file=nil ...>
238 >> template.render
239 => "<h1>Hello Haml!</h1>"
240
241 __NOTE:__ It's suggested that your program `require 'haml'` at load time when
242 using this template engine within a threaded environment.
243
244 ### Options
245
3fbde0d @mattwildig Update links to Haml site
mattwildig authored
246 Please see the [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options) for all available options.
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
247
248 ### See also
249
3fbde0d @mattwildig Update links to Haml site
mattwildig authored
250 * [#haml.docs](http://haml.info/docs.html)
251 * [Haml Tutorial](http://haml.info/tutorial.html)
252 * [Haml Reference](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html)
2a4b2c0 @rtomayko add erubis, haml, and mustache docs to TEMPLATES.md
authored
253
254
4eeaac4 @rtomayko add basic liquid docs
authored
255 <a name='liquid'></a>
256 Liquid (`liquid`)
257 -----------------
258
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
259 [Liquid][liquid] is for rendering safe templates which cannot affect the
260 security of the server they are rendered on.
4eeaac4 @rtomayko add basic liquid docs
authored
261
262 ### Example
263
264 <html>
265 <head>
266 <title>{{ title }}</title>
267 </head>
268 <body>
269 <h1>Hello {{ world }}!</h1>
270 </body>
271 </html>
272
273 ### Usage
274
275 `Tilt::LiquidTemplate` is registered for all files ending in `.liquid` by
276 default. Liquid templates support locals and objects that respond to
277 `#to_h` as scopes:
278
279 >> require 'liquid'
280 >> require 'tilt'
281 >> template = Tilt.new('hello.liquid')
282 => #<Tilt::LiquidTemplate @file='hello.liquid'>
283 >> scope = { :title => "Hello Liquid Templates" }
284 >> template.render(nil, :world => "Liquid")
285 => "
286 <html>
287 <head>
288 <title>Hello Liquid Templates</title>
289 </head>
290 <body>
291 <h1>Hello Liquid!</h1>
292 </body>
293 </html>"
294
295 Or, use `Tilt::LiquidTemplate` directly to process strings:
296
27b0875 @mattwildig Fix copy and paste error
mattwildig authored
297 >> require 'liquid'
b52ddae @judofyr Add documentation for fallback mode
judofyr authored
298 >> template = Tilt::LiquidTemplate.new { "<h1>Hello Liquid!</h1>" }
4eeaac4 @rtomayko add basic liquid docs
authored
299 => #<Tilt::LiquidTemplate @file=nil ...>
300 >> template.render
301 => "<h1>Hello Liquid!</h1>"
302
303 __NOTE:__ It's suggested that your program `require 'liquid'` at load
304 time when using this template engine within a threaded environment.
305
306 ### See also
307
308 * [Liquid for Programmers](http://wiki.github.com/tobi/liquid/liquid-for-programmers)
309 * [Liquid Docs](http://liquid.rubyforge.org/)
310 * GitHub: [tobi/liquid](http://github.com/tobi/liquid/)
311
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
312
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
313 <a name='radius'></a>
314 Radius (`radius`)
315 -----------------
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
316
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
317 [Radius][radius] is the template language used by [Radiant CMS][radiant]. It is
318 a tag language designed to be valid XML/HTML.
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
319
320 ### Example
321
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
322 <html>
323 <body>
324 <h1><r:title /></h1>
325 <ul class="<r:type />">
326 <r:repeat times="3">
327 <li><r:hello />!</li>
328 </r:repeat>
329 </ul>
330 <r:yield />
331 </body>
332 </html>
23a141b @rtomayko RDocTemplate specs and docs
authored
333
334 ### Usage
335
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
336 To render a template such as the one above.
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
337
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
338 scope = OpenStruct.new
339 scope.title = "Radius Example"
340 scope.hello = "Hello, World!"
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
341
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
342 require 'radius'
343 template = Tilt::RadiusTemplate.new('example.radius', :tag_prefix=>'r')
344 template.render(scope, :type=>'hlist'){ "Jackpot!" }
23a141b @rtomayko RDocTemplate specs and docs
authored
345
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
346 The result will be:
347
348 <html>
349 <body>
350 <h1>Radius Example</h1>
351 <ul class="hlist">
352 <li>Hello, World!</li>
353 <li>Hello, World!</li>
354 <li>Hello, World!</li>
355 </ul>
356 Jackpot!
357 </body>
358 </html>
2f2aa38 @rtomayko :smart and :filter_html options for RDiscountTemplate
authored
359
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
360 ### See also
2f2aa38 @rtomayko :smart and :filter_html options for RDiscountTemplate
authored
361
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
362 * [Radius][radius]
363 * [Radiant CMS][radiant]
2f2aa38 @rtomayko :smart and :filter_html options for RDiscountTemplate
authored
364
365
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
366 <a name='textile'></a>
367 Textile (`textile`)
368 -------------------
2f2aa38 @rtomayko :smart and :filter_html options for RDiscountTemplate
authored
369
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
370 Textile is a lightweight markup language originally developed by Dean Allen and
371 billed as a "humane Web text generator". Textile converts its marked-up text
372 input to valid, well-formed XHTML and also inserts character entity references
373 for apostrophes, opening and closing single and double quotation marks,
374 ellipses and em dashes.
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
375
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
376 Textile formatted texts are converted to HTML with the [RedCloth][redcloth]
377 engine, which is a Ruby extension written in C.
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
378
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
379 ### Example
6f180e3 @rtomayko added markdown doc to TEMPLATES
authored
380
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
381 h1. Hello Textile Templates
3922e7d Remove whitespace [Gun.io WhitespaceBot]
Gun.io Whitespace Robot authored
382
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
383 Hello World. This is a paragraph.
384
385 ### Usage
386
387 __NOTE:__ It's suggested that your program `require 'redcloth'` at load time
388 when using this template engine in a threaded environment.
389
390 ### See Also
391
392 * [RedCloth][redcloth]
23a141b @rtomayko RDocTemplate specs and docs
authored
393
394
395 <a name='rdoc'></a>
396 RDoc (`rdoc`)
397 -------------
398
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
399 [RDoc][rdoc] is the simple text markup system that comes with Ruby's standard
23a141b @rtomayko RDocTemplate specs and docs
authored
400 library.
401
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
402 ### Example
403
404 = Hello RDoc Templates
405
406 Hello World. This is a paragraph.
407
23a141b @rtomayko RDocTemplate specs and docs
authored
408 ### Usage
409
ecdf148 @timfel rdoc 3.10 autoloads everything, so you _have_ to require 'rdoc' direc…
timfel authored
410 __NOTE:__ It's suggested that your program `require 'rdoc'`,
411 `require 'rdoc/markup'`, and `require 'rdoc/markup/to_html'` at load time
412 when using this template engine in a threaded environment.
23a141b @rtomayko RDocTemplate specs and docs
authored
413
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
414 ### See also
23a141b @rtomayko RDocTemplate specs and docs
authored
415
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
416 * [RDoc][rdoc]
23a141b @rtomayko RDocTemplate specs and docs
authored
417
418
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
419 <a name='markdown'></a>
420 Markdown (`markdown`, `md`, `mkd`)
421 ----------------------------------
23a141b @rtomayko RDocTemplate specs and docs
authored
422
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
423 [Markdown][markdown] is a lightweight markup language, created by John Gruber
424 and Aaron Swartz. For any markup that is not covered by Markdown’s syntax, HTML
425 is used. Marking up plain text with Markdown markup is easy and Markdown
426 formatted texts are readable.
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
427
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
428 Markdown formatted texts are converted to HTML with one of these libraries:
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
429
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
430 * [RDiscount](#rdiscount) - `Tilt::RDiscountTemplate`
ad1d9f7 @rkh add Redcarpet to template docs
rkh authored
431 * Redcarpet - `Tilt::RedcarpetTemplate`
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
432 * BlueCloth - `Tilt::BlueClothTemplate`
433 * Kramdown - `Tilt::KramdownTemplate`
434 * Maruku - `Tilt::MarukuTemplate`
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
435
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
436 Tilt will use fallback mode (as documented in the README) for determining which
3922e7d Remove whitespace [Gun.io WhitespaceBot]
Gun.io Whitespace Robot authored
437 library to use. RDiscount has highest priority - Maruku has lowest.
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
438
439 ### Example
440
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
441 Hello Markdown Templates
442 ========================
443
444 Hello World. This is a paragraph.
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
445
446 ### Usage
447
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
448 To wrap a Markdown formatted document with a layout:
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
449
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
450 layout = Tilt['erb'].new do
451 "<!doctype html><title></title><%= yield %>"
452 end
453 data = Tilt['md'].new { "# hello tilt" }
454 layout.render { data.render }
455 # => "<!doctype html><title></title><h1>hello tilt</h1>\n"
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
456
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
457 ### Options
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
458
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
459 Every implementation of Markdown *should* support these options, but there are
460 some known problems with the Kramdown and Maruku engines.
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
461
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
462 #### `:smartypants => true|false`
463
464 Set `true` to enable [Smarty Pants][smartypants]
465 style punctuation replacement.
466
467 #### `:escape_html => true|false`
468
469 Set `true` disallow raw HTML in Markdown contents. HTML is converted to
470 literal text by escaping `<` characters.
471
472 ### See also
473
474 * [Markdown Syntax Documentation](http://daringfireball.net/projects/markdown/syntax/)
475
476 <a name='rdiscount'></a>
477 RDiscount (`markdown`, `md`, `mkd`)
478 -----------------------------------
479
480 [Discount][discount] is an implementation of the Markdown markup language in C.
481 [RDiscount][rdiscount] is a Ruby wrapper around Discount.
482
483 All the documentation of [Markdown](#markdown) applies in addition to the following:
484
485 ### Usage
486
487 The `Tilt::RDiscountTemplate` class is registered for all files ending in
488 `.markdown`, `.md` or `.mkd` by default with the highest priority. If you
489 specifically want to use RDiscount, it's recommended to use `#prefer`:
490
491 Tilt.prefer Tilt::RDiscountTemplate
492
493 __NOTE:__ It's suggested that your program `require 'erubis'` at load time when
494 using this template engine within a threaded environment.
c43c8d1 @trans add documentation for Radius and improve implementation
trans authored
495
496 ### See also
497
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
498 * [Discount][discount]
499 * [RDiscount][rdiscount]
500 * GitHub: [rtomayko/rdiscount][rdiscount]
501
502
503 [lesscss]: http://lesscss.org/ "Less CSS"
504 [sass]: http://sass-lang.com/ "Sass"
505 [coffee-script]: http://jashkenas.github.com/coffee-script/ "Coffee Script"
506 [erubis]: http://www.kuwata-lab.com/erubis/ "Erubis"
3fbde0d @mattwildig Update links to Haml site
mattwildig authored
507 [haml]: http://haml.info/ "Haml"
42ea5cb @judofyr Clean up TEMPLATES.md (#69, #74)
judofyr authored
508 [liquid]: http://www.liquidmarkup.org/ "Liquid"
509 [radius]: http://radius.rubyforge.org/ "Radius"
510 [radiant]: http://radiantcms.org/ "Radiant CMS"
511 [redcloth]: http://redcloth.org/ "RedCloth"
512 [rdoc]: http://rdoc.rubyforge.org/ "RDoc"
513 [discount]: http://www.pell.portland.or.us/~orc/Code/discount/ "Discount"
514 [rdiscount]: http://github.com/rtomayko/rdiscount/ "RDiscount"
515 [smartypants]: http://daringfireball.net/projects/smartypants/ "Smarty Pants"
516
Something went wrong with that request. Please try again.