Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 334 lines (212 sloc) 8.384 kB
61eee29 @tj Started readme
tj authored
1
2 # Jade - template engine
3
2849e11 @tj Added features
tj authored
4 Jade is a high performance template engine heavily influenced by [Haml](http://haml-lang.com)
5 and implemented with JavaScript for [node](http://nodejs.org).
6
7 ## Features
8
9 - high performance parser
10 - great readability
11 - code is escaped by default for security
12 - contextual error reporting at compile & run time
690f915 @tj More features
tj authored
13 - executable for compiling jade templates via the command line
14 - html 5 mode (using the _!!! 5_ doctype)
15 - optional memory caching
e104867 @tj Filter docs
tj authored
16 - combine dynamic and static tag classes
cd67780 @tj Added feature to list
tj authored
17 - supports [Express JS](http://expressjs.com)
77fa5ca @tj Added -each docs
tj authored
18 - transparent iteration over objects, arrays, and even non-enumerables via `- each`
2849e11 @tj Added features
tj authored
19 - no tag prefix
20 - filters
edc190b @tj Fixed markdown support
tj authored
21 - :sass must have [sass.js](http://github.com/visionmedia/sass.js) installed
22 - :less must have [less.js](http://github.com/cloudhead/less.js) installed
efafcfe @tj Added node-discount in readme
tj authored
23 - :markdown must have [markdown-js](http://github.com/evilstreak/markdown-js) installed or [node-discount](http://github.com/visionmedia/node-discount)
2849e11 @tj Added features
tj authored
24 - :cdata
25 - :javascript
0accfe7 @tj Added link to textmate bundle
tj authored
26 - [TextMate Bundle](http://github.com/miksago/jade-tmbundle)
2849e11 @tj Added features
tj authored
27
dcbc04f @tj Implementations section
tj authored
28 ## Implementations
29
a74428a @tj Changed jade.php link
tj authored
30 - [php](http://github.com/everzet/jade.php)
dcbc04f @tj Implementations section
tj authored
31 - [client-side js](http://github.com/miksago/jade)
32
a9a5fd5 @tj Added install docs / seed.yml
tj authored
33 ## Installation
34
35 via tarball or git:
36
37 make install
38
39 via npm:
40
41 npm install jade
42
7ece7e6 @tj Public api docs
tj authored
43 ## Public API
44
45 var jade = require('jade');
46
47 // Render a string
48 jade.render('string of jade', { options: 'here' });
49
50 // Render a file
51 jade.renderFile('path/to/some.jade', { options: 'here' }, function(err, html){
52 // options are optional,
53 // the callback can be the second arg
54 });
55
77b3264 @tj Docs for render()
tj authored
56 ### Options
57
58 - `scope` Evaluation scope (`this`)
59 - `locals` Local variable object
60 - `filename` Used in exceptions, and required by `cache`
61 - `cache` Cache intermediate JavaScript in memory keyed by `filename`
f57202e @tj Added debug option to readme
tj authored
62 - `debug` Outputs tokens and function body generated
77b3264 @tj Docs for render()
tj authored
63
39ca646 @tj More docs
tj authored
64 ## Syntax
65
66 ### Line Endings
67
6c2333b @tj Doc typo
tj authored
68 **CRLF** and **CR** are converted to **LF** before parsing.
39ca646 @tj More docs
tj authored
69
70 ### Indentation
71
72 Jade is indentation based, however currently only supports a _2 space_ indent.
73 We may implement tab support in the future, until then use spaces, so make sure soft
74 tabs are enabled in your editor.
75
8c6488f @tj Tag docs
tj authored
76 ### Tags
77
78 A tag is simply a leading word:
79
80 html
81
82 for example is converted to `<html></html>`
83
f61bf53 @tj More tag docs
tj authored
84 tags can also have ids:
85
86 div#container
87
88 which would render `<div id="container"></div>`
89
90 how about some classes?
91
92 div.user-details
93
94 renders `<div class="user-details"></div>`
95
96 multiple classes? _and_ an id? sure:
97
98 div#foo.bar.baz
99
100 renders `<div id="foo" class="bar baz"></div>`
101
102 div div div sure is annoying, how about:
103
104 #foo
105 .bar
106
107 which is syntactic sugar for what we have already been doing, and outputs:
108
109 `<div id="foo"></div><div class="bar"></div>`
110
346bda8 @tj Tag text docs
tj authored
111 ### Tag Text
112
113 Simply place some content after the tag:
114
115 p wahoo!
90e0ebd @tj Added interpolation docs
tj authored
116
117 renders `<p>wahoo!</p>`.
118
119 well cool, but how about large bodies of text:
120
121 p
122 | foo bar baz
123 | rawr rawr
124 | super cool
125 | go jade go
126
127 renders `<p>foo bar baz rawr.....</p>`
128
129 interpolation? yup! both types of text can utilize interpolation,
130 if we passed `{ locals: { name: 'tj', email: 'tj@vision-media.ca' }}` to `render()`
131 we can do the following:
132
133 #user #{name} &lt;#{email}&gt;
134
135 outputs `<div id="user">tj &lt;tj@vision-media.ca&gt;</div>`
346bda8 @tj Tag text docs
tj authored
136
01f4f62 @tj Interpolation escape docs
tj authored
137 Actually want `#{}` for some reason? escape it!
138
139 p \#{something}
140
141 now we have `<p>#{something}</p>`
142
39ca646 @tj More docs
tj authored
143 ### Nesting
144
145 ul
146 li one
147 li two
148 li three
149
a0ee2c0 @tj More docs
tj authored
150 Fucked up your whitespace? no worries, jade's error reporting should help you out.
151 Jade instruments the compiled JavaScript to provide meaningful context for runtime exceptions.
39ca646 @tj More docs
tj authored
152
153 ul
154 li one
155 li two
156
157 Error: /Users/tj/Projects/jade/examples/layout.jade:2
158 1. 'ul'
159 2. ' li one'
160
161 Invalid indentation, got 2 expected 1.
162
163 Note: Trailing are generated on **EOS** if not present.
164
165 ### Attributes
166
167 Jade currently supports '(' and ')' as attribute delimiters.
168
169 a(href='/login', title='View login page') Login
170
171 Alternatively we may use the colon to separate pairs:
172
173 a(href: '/login', title: 'View login page') Login
174
58ed759 @tj Doctypes
tj authored
175 Boolean attributes are also supported:
176
177 input(type="checkbox", checked)
178
179 Boolean attributes with code will only output the attribute when `true`:
180
181 input(type="checkbox", checked: someValue)
182
39ca646 @tj More docs
tj authored
183 Note: Leading / trailing whitespace is _ignore_ for attr pairs.
184
58ed759 @tj Doctypes
tj authored
185 ### Doctypes
186
187 To add a doctype simply use `!!!` followed by an optional value:
188
189 !!!
190
191 Will output the _transitional_ doctype, however:
192
193 !!! 5
194
195 Will output html 5's doctype. Below are the doctypes
196 defined by default, which can easily be extended:
197 var doctypes = exports.doctypes = {
198 '5': '<!DOCTYPE html>',
199 'xml': '<?xml version="1.0" encoding="utf-8" ?>',
200 'default': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
201 'transitional': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
202 'strict': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
203 'frameset': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
204 '1.1': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
205 'basic': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">',
206 'mobile': '<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">'
207 };
208
f168fb8 @tj Added docs for changing default doctype
tj authored
209 To alter the default simply change:
210
211 jade.doctypes.default = 'whatever you want';
212
e104867 @tj Filter docs
tj authored
213 ## Filters
214
215 Filters are prefixed with `:`, for example `:markdown` and
216 pass the following block of text to an arbitrary function for processing. View the _features_
217 at the top of this document for available filters.
218
219 body
220 :markdown
221 | Woah! jade _and_ markdown, very **cool**
222 | we can even link to [stuff](http://google.com)
223
224 Renders:
225
226 <body><p>Woah! jade <em>and</em> markdown, very <strong>cool</strong> we can even link to <a href="http://google.com">stuff</a></p></body>
227
dedd519 @tj Code docs
tj authored
228 ## Code
229
230 Jade currently supports three classifications of executable code. The first
231 is prefixed by `-`, and is not buffered:
232
233 - var foo = 'bar';
234
235 This can be used for conditionals, or iteration:
236
237 - for (var key in obj)
238 p= obj[key]
239
240 Due to Jade's buffering techniques the following is valid as well:
241
242 - if (foo)
243 ul
244 li yay
245 li foo
246 li worked
247 - else
248 p shit! didnt work
249
13b2346 @tj Typo in docs
tj authored
250 Hell, even verbose iteration:
dedd519 @tj Code docs
tj authored
251
252 - if (items.length)
253 ul
254 - items.forEach(function(item){
255 li= item
256 - })
257
258 Anything you want!
259
260 Next up we have _escaped_ buffered code, which is used to
261 buffer a return value, which is prefixed by `=`:
262
263 - var foo = 'bar'
264 = foo
265 h1= foo
266
267 Which outputs `bar<h1>bar<h1/>`. Code buffered by `=` is escaped
268 by default for security, however to output unescaped return values
269 you may use `!=`:
270
271 p!= aVarContainingMoreHTML
272
77fa5ca @tj Added -each docs
tj authored
273 The on exception made in terms of allowing "vanilla" JavaScript, is
274 the `- each` token. This takes the form of:
275
276 - each VAL[, KEY] in OBJ
277
278 An example iterating over an array:
279
280 - var items = ["one", "two", "three"]
281 - each item in items
282 li= item
283
284 outputs:
285
286 <li>one</li>
287 <li>two</li>
288 <li>three</li>
289
290 iterating an object's keys and values:
291
292 - var obj = { foo: 'bar' }
293 - each val, key in obj
294 li #{key}: #{val}
295
296 would output `<li>foo: bar</li>`
297
298 Non-enumerables are simply passed as the **only** value:
299
300 - each n in 15
301 li= n
302
303 would simply output `<li>15</li>`
304
305 You can also nest these!
306
307 - each user in users
308 - each role in user.roles
309 li= role
310
61eee29 @tj Started readme
tj authored
311 ## bin/jade
312
313 Output html to _stdout_:
314
315 jade examples/*.jade --pipe
316
317 Generate _examples/*.html_:
318
319 jade examples/*.jade
320
321 Pass options:
322
323 jade examples/layout.jade --options '{ locals: { title: "foo" }}'
324
325 Usage info:
326
327 Usage: jade [options] <path ...>
328
329 Options:
330 -o, --options STR JavaScript options object passed
331 -p, --pipe Output to stdout instead of PATH.html
332 -h, --help Output help information
333
Something went wrong with that request. Please try again.