Jade - template engine

Through the use of Jade's ./runtime.js you may utilize these pre-compiled templates on the client-side _without_ Jade itself, all you need is the associated utility functions (in runtime.js), which are then available as jade.attrs, jade.escape etc. To enable this you should pass { client: true } to jade.compile()to tell Jade to reference the helper functions viajade.attrs, jade.escape etc.

`js function anonymous(locals, attrs, escape, rethrow) { var attrs = jade.attrs, escape = jade.escape, rethrow = jade.rethrow; var buf = []; with (locals || {}) { var interp; buf.push('\n

Hello ' + escape((interp = name) == null ? '' : interp) + '\n

');
  }
  return buf.join("");
}


Public API

`js var jade = require('jade');

// Compile a function var fn = jade.compile('string of jade', options); fn(locals);`

`$3`

- self Use a selfnamespace to hold the locals _(false by default)_ -localsLocal variable object -filenameUsed in exceptions, and required when using includes -debugOutputs tokens and function body generated -compilerCompiler to replace jade's default -compileDebug When falseno debug instrumentation is compiled -pretty Add pretty-indentation whitespace to output _(false by default)_

`Syntax`

`$3`

CRLF and CR are converted to LF before parsing.

`$3`

A tag is simply a leading word:

`jade html`

for example is converted to

tags can also have ids:

`jade div#container`

which would render


how about some classes?

`jade div.user-details`

renders


multiple classes? _and_ an id? sure:

`jade div#foo.bar.baz`

renders


div div div sure is annoying, how about:

`jade #foo .bar`

which is syntactic sugar for what we have already been doing, and outputs:

`html


$3
Simply place some content after the tag:

`jade p wahoo!`

renders

wahoo!

.
well cool, but how about large bodies of text:

`jade p | foo bar baz | rawr rawr | super cool | go jade go`

renders

foo bar baz rawr.....

interpolation? yup! both types of text can utilize interpolation, if we passed{ name: 'tj', email: 'tj@vision-media.ca' } to the compiled function we can do the following:

`jade #user #{name} <#{email}>`

outputs

tj <tj@vision-media.ca>

Actually want #{} for some reason? escape it!

`jade p \#{something}`

now we have

#{something}

We can also utilize the unescaped variant !{html}, so the following will result in a literal script tag:

`jade - var html = "" | !{html}`

Nested tags that also contain text can optionally use a text block:

`jade label | Username: input(name='user[name]')`

or immediate tag text:

`jade label Username: input(name='user[name]')`

Tags that accept _only_ text such as script and styledo not need the leading| character, for example:

`jade html head title Example script if (foo) { bar(); } else { baz(); }`

Once again as an alternative, we may use a trailing . to indicate a text block, for example:

`jade p. foo asdf asdf asdfasdfaf asdf asd.`

outputs:

`html

foo asdf asdf asdfasdfaf asdf asd.

This however differs from a trailing . followed by a space, which although is ignored by the Jade parser, tells Jade that this period is a literal:

`jade p .`

outputs:

`html

.


It should be noted that text blocks should be doubled escaped.  For example if you desire the following output.

`html

foo\bar


use:

`jade p. foo\\bar`

`$3`

Single line comments currently look the same as JavaScript comments, aka// and must be placed on their own line:

`jade // just some paragraphs p foo p bar`

would output

`html

foo

bar


Jade also supports unbuffered comments, by simply adding a hyphen:

`jade //- will not output within markup p foo p bar`

outputting

`html

foo

bar


$3
 A block comment is legal as well:

`jade body // #content h1 Example`

outputting

`html`

Jade supports conditional-comments as well, for example:

`jade head //if lt IE 8 script(src='/ie-sucks.js')`

outputs:

`html`

`Title`


    | foo bar baz

Or we can use the trailing .to indicate to Jade that we only want text in this block, allowing us to omit the pipes:

`jade html body.

`Title`


    foo bar baz


 Both of these examples yield the same result:

`html

`Title`


foo bar baz


 The same rule applies for anywhere you can have text
 in jade, raw html is fine:

`jade html body h1 User #{name}`

`$3`

To add a doctype simply use !!!, or doctype followed by an optional value:

`jade !!!`

or

`jade doctype`

Will output the _html 5_ doctype, however:

`jade !!! transitional`

Will output the _transitional_ doctype.

Doctypes are case-insensitive, so the following are equivalent:

`jade doctype Basic doctype basic`

it's also possible to simply pass a doctype literal:

`jade doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN`

yielding:

`html`

Below are the doctypes defined by default, which can easily be extended:

`js var doctypes = exports.doctypes = { '5': '', 'default': '', 'xml': '', 'transitional': '', 'strict': '', 'frameset': '', '1.1': '', 'basic': '', 'mobile': '' };`

To alter the default simply change:

`js jade.doctypes.default = 'whatever you want';`

`Filters`

Filters are prefixed with :, for example :markdownand pass the following block of text to an arbitrary function for processing. View the _features_ at the top of this document for available filters.

`jade body :markdown Woah! jade _and_ markdown, very cool we can even link tostuff`

Renders:

`html

Woah! jade and markdown, very cool we can even link to stuff



Code

Jade currently supports three classifications of executable code. The first is prefixed by-, and is not buffered:

`jade - var foo = 'bar';`

This can be used for conditionals, or iteration:

`jade - for (var key in obj) p= obj[key]`

Due to Jade's buffering techniques the following is valid as well:

`jade - if (foo) ul li yay li foo li worked - else p oh no! didnt work`

Hell, even verbose iteration:

`jade - if (items.length) ul - items.forEach(function(item){ li= item - })`

Anything you want!

Next up we have _escaped_ buffered code, which is used to buffer a return value, which is prefixed by=:

`jade - var foo = 'bar' = foo h1= foo`

Which outputs bar

bar

. Code buffered by =

 is escaped
by default for security, however to output unescaped return values
you may use

!=:

`jade p!= aVarContainingMoreHTML`

Jade also has designer-friendly variants, making the literal JavaScript more expressive and declarative. For example the following assignments are equivalent, and the expression is still regular javascript:

`jade - var foo = 'foo ' + 'bar' foo = 'foo ' + 'bar'`

Likewise Jade has first-class if, else if, else, until, while, unless among others, however you must remember that the expressions are still regular javascript:

`jade if foo == 'bar' ul li yay li foo li worked else p oh no! didnt work`

`Iteration`

Along with vanilla JavaScript Jade also supports a subset of constructs that allow you to create more designer-friendly templates, one of these constructs iseach, taking the form:

`jade each VAL[, KEY] in OBJ`

An example iterating over an array:

`jade - var items = ["one", "two", "three"] each item in items li= item`

outputs:

`html

one


two

three


iterating an array with index:

`jade items = ["one", "two", "three"] each item, i in items li #{item}: #{i}`

outputs:

`html

one: 0


two: 1

three: 2


iterating an object's keys and values:

`jade obj = { foo: 'bar' } each val, key in obj li #{key}: #{val}`

would output

foo: bar

Internally Jade converts these statements to regular JavaScript loops such asusers.forEach(function(user){, so lexical scope and nesting applies as it would with regular JavaScript:

`jade each user in users each role in user.roles li= role`

You may also use for if you prefer:

`jade for user in users for role in user.roles li= role`

`Conditionals`

Jade conditionals are equivalent to those using the code (-) prefix, however allow you to ditch parenthesis to become more designer friendly, however keep in mind the expression given is _regular_ JavaScript:

`jade for user in users if user.role == 'admin' p #{user.name} is an admin else p= user.name`

is equivalent to the following using vanilla JavaScript literals:

`jade for user in users - if (user.role == 'admin') p #{user.name} is an admin - else p= user.name`

Jade also provides unless which is equivalent to if (!(expr)):

`jade for user in users unless user.isAnonymous p | Click to view a(href='/users/' + user.id)= user.name`

`Template inheritance`

Jade supports template inheritance via the block and extends keywords. A block is simply a "block" of Jade that may be replaced within a child template, this process is recursive. To activate template inheritance in Express 2.x you must add: app.set('view options', { layout: false });.

Jade blocks can provide default content if desired, however optional as shown below by block scripts, block content, and block foot.

`jade html head h1 My Site - #{title} block scripts script(src='/jquery.js') body block content block foot #footer p some footer content`

Now to extend the layout, simply create a new file and use the extends directive as shown below, giving the path (with or without the .jade extension). You may now define one or more blocks that will override the parent block content, note that here the foot block is _not_ redefined and will output "some footer content".

`jade extends layout

block scripts script(src='/jquery.js') script(src='/pets.js')

block content h1= title each pet in pets include pet`

It's also possible to override a block to provide additional blocks, as shown in the following example where content now exposes a sidebar and primary block for overriding, or the child template could override content all together.

`jade extends regular-layout

block content .sidebar block sidebar p nothing .primary block primary p nothing`

`Block append / prepend`

Jade allows you to _replace_ (default), _prepend_, or _append_ blocks. Suppose for example you have default scripts in a "head" block that you wish to utilize on _every_ page, you might do this:

`jade html head block head script(src='/vendor/jquery.js') script(src='/vendor/caustic.js') body block content`

Now suppose you have a page of your application for a JavaScript game, you want some game related scripts as well as these defaults, you can simply append the block:

`jade extends layout

block append head script(src='/vendor/three.js') script(src='/game.js')`

When using block append or block prepend the block is optional:

`jade extends layout

append head script(src='/vendor/three.js') script(src='/game.js')`

`Includes`

Includes allow you to statically include chunks of Jade, or other content like css, or html which lives in separate files. The classical example is including a header and footer. Suppose we have the following directory structure:

./layout.jade ./includes/ ./head.jade ./foot.jade

and the following _layout.jade_:

`jade html include includes/head body h1 My Site p Welcome to my super amazing site. include includes/foot`

both includes _includes/head_ and _includes/foot_ are read relative to thefilenameoption given to _layout.jade_, which should be an absolute path to this file, however Express does this for you. Include then parses these files, and injects the AST produced to render what you would expect:

`html My Site

`My Site`


    Welcome to my super lame site.

    
      Copyright>(c) foobar

As mentioned includecan be used to include other content such as html or css. By providing an extension Jade will not assume that the file is Jade source and will include it as a literal:

`jade html body include content.html`

Include directives may also accept a block, in which case the the given block will be appended to the _last_ block defined in the file. For example ifhead.jade contains:

`jade head script(src='/jquery.js')`

We may append values by providing a block to include headas shown below, adding the two scripts.

`jade html include head script(src='/foo.js') script(src='/bar.js') body h1 test`

You may also yield within an included template, allowing you to explicitly mark where the block given to include will be placed. Suppose for example you wish to prepend scripts rather than append, you might do the following:

`jade head yield script(src='/jquery.js') script(src='/jquery.ui.js')`

Since included Jade is parsed and literally merges the AST, lexically scoped variables function as if the included Jade was written right in the same file. This means include may be used as sort of partial, for example suppose we have user.jade which utilizes a user variable.

`jade h1= user.name p= user.occupation`

We could then simply include user while iterating users, and since the user variable is already defined within the loop the included template will have access to it.

`jade users = [{ name: 'Tobi', occupation: 'Ferret' }]

each user in users .user include user`

yielding:

`html


  Tobi

  Ferret

If we wanted to expose a different variable name as user since user.jade references that name, we could simply define a new variable as shown here with user = person:

`jade each person in users .user user = person include user`

`Mixins`

Mixins are converted to regular JavaScript functions in the compiled template that Jade constructs. Mixins may take arguments, though not required:

`jade mixin list ul li foo li bar li baz`

Utilizing a mixin without args looks similar, just without a block:

`jade h2 Groceries mixin list`

Mixins may take one or more arguments as well, the arguments are regular javascripts expressions, so for example the following:

`jade mixin pets(pets) ul.pets - each pet in pets li= pet

mixin profile(user) .user h2= user.name mixin pets(user.pets)`

Would yield something similar to the following html:

`html


  tj

  
    tobi

    loki

    jane

    manny


Generated Output
 Suppose we have the following Jade:

`jade - var title = 'yay' h1.title #{title} p Just an example`

When the compileDebug option is not explicitly false, Jade will compile the function instrumented with__.lineno = n;, which in the event of an exception is passed torethrow()which constructs a useful message relative to the initial Jade input.

`js function anonymous(locals) { var __ = { lineno: 1, input: "- var title = 'yay'\nh1.title #{title}\np Just an example", filename: "testing/test.js" }; var rethrow = jade.rethrow; try { var attrs = jade.attrs, escape = jade.escape; var buf = []; with (locals || {}) { var interp; __.lineno = 1; var title = 'yay' __.lineno = 2; buf.push(' buf.push(attrs({ "class": ('title') })); buf.push('>'); buf.push('' + escape((interp = title) == null ? '' : interp) + ''); buf.push(''); __.lineno = 3; buf.push('

'); buf.push('Just an example'); buf.push('

');
    }
    return buf.join("");
  } catch (err) {
    rethrow(err, __.input, __.filename, __.lineno);
  }
}

When the compileDebug option _is_ explicitly false, this instrumentation is stripped, which is very helpful for light-weight client-side templates. Combining Jade's options with the./runtime.jsfile in this repo allows you to toString() compiled templates and avoid running the entire Jade library on the client, increasing performance, and decreasing the amount of JavaScript required.

`js function anonymous(locals) { var attrs = jade.attrs, escape = jade.escape; var buf = []; with (locals || {}) { var interp; var title = 'yay' buf.push(' buf.push(attrs({ "class": ('title') })); buf.push('>'); buf.push('' + escape((interp = title) == null ? '' : interp) + ''); buf.push(''); buf.push('

'); buf.push('Just an example'); buf.push('

');
  }
  return buf.join("");
}


Example Makefile

Below is an example Makefile used to compile _pages/*.jade_ into _pages/*.html_ files by simply executingmake.

_Note:_ If you try to run this snippet and make throws a missing separator error, you should make sure all indented lines use a tab for indentation instead of spaces. (For whatever reason, GitHub renders this code snippet with 4-space indentation although the actual README file uses tabs in this snippet.)

`make JADE = $(shell find . -wholename './pages/*.jade') HTML = $(JADE:.jade=.html)

all: $(HTML)

%.html: %.jade jade < $< --path $< > $@

clean: rm -f $(HTML)

.PHONY: clean`

this can be combined with the watch(1)command to produce a watcher-like behaviour:

`bash $ watch make`

`jade(1)`

Usage: jade [options] [dir|file ...]

Options:

-h, --help output usage information -V, --version output the version number -o, --obj javascript options object -O, --out

output the compiled html to


  -p, --path   filename used to resolve includes
  -P, --pretty       compile pretty html output
  -c, --client       compile for client-side runtime.js
  -D, --no-debug     compile without debugging (smaller functions)
Examples:
  # translate jade the templates dir
  $ jade templates
  # create {foo,bar}.html
  $ jade {foo,bar}.jade
  # jade over stdio
  $ jade < my.jade > my.html
  # jade over stdio
  $ echo "h1 Jade!" | jade
  # foo, bar dirs rendering to /tmp
  $ jade foo bar --out /tmp