jade

What is jade?

Jade, now known as Pug, is a high-performance template engine heavily influenced by Haml and implemented with JavaScript for Node.js and browsers. It is used to generate HTML dynamically and is known for its clean and minimal syntax.

What are jade's main functionalities?

Template Rendering

Jade allows you to render HTML templates with dynamic data. In this example, a simple template is rendered with a variable 'name' which is replaced with 'World'.

const pug = require('pug');
const html = pug.render('p Hello, #{name}!', { name: 'World' });
console.log(html);

Template Inheritance

Jade supports template inheritance, allowing you to create a base template and extend it in other templates. This example demonstrates how 'index.pug' extends 'layout.pug' and defines a content block.

const pug = require('pug');
const html = pug.renderFile('index.pug');
console.log(html);
// index.pug
// extends layout.pug
// block content
//   h1= title
//   p Welcome to #{title}
// layout.pug
// doctype html
// html
//   head
//     title= title
//   body
//     block content

Mixins

Mixins in Jade allow you to create reusable blocks of code. This example shows a mixin 'list' that generates an unordered list from an array of items.

const pug = require('pug');
const html = pug.renderFile('mixin.pug');
console.log(html);
// mixin.pug
// mixin list(items)
//   ul
//     each item in items
//       li= item
// +list(['Apple', 'Banana', 'Cherry'])

Other packages similar to jade

ejs

EJS (Embedded JavaScript) is a simple templating language that lets you generate HTML markup with plain JavaScript. It is similar to Jade but uses a more traditional syntax that is closer to HTML, making it easier for those familiar with HTML to use.

handlebars

Handlebars is a popular templating engine that provides the power necessary to let you build semantic templates effectively with no frustration. It is known for its simplicity and logic-less templates, which makes it different from Jade's more feature-rich approach.

mustache

Mustache is a logic-less template syntax. It is named 'logic-less' because it lacks any explicit control flow statements like if and else. This makes it very different from Jade, which supports more complex logic and features.

README

Jade - template engine

Jade is a high performance template engine heavily influenced by Haml and implemented with JavaScript for node.

Features

• client-side support
• great readability
• flexible indentation
• block-expansion
• mixins
• static includes
• attribute interpolation
• code is escaped by default for security
• contextual error reporting at compile & run time
• executable for compiling jade templates via the command line
• html 5 mode (using the !!! 5 doctype)
• optional memory caching
• combine dynamic and static tag classes
• parse tree manipulation via filters
• supports Express JS out of the box
• transparent iteration over objects, arrays, and even non-enumerables via - each
• block comments
• no tag prefix
• AST filters
• filters
  • :sass must have sass.js installed
  • :less must have less.js installed
  • :markdown must have markdown-js installed or node-discount
  • :cdata
  • :coffeescript must have coffee-script installed
• Vim Syntax
• TextMate Bundle
• Screencasts
• html2jade converter

Implementations

• php
• scala
• ruby

Installation

via npm:

npm install jade

Browser Support

To compile jade to a single file compatible for client-side use simply execute:

$ make jade.js

Alternatively, if uglifyjs is installed via npm (npm install uglify-js) you may execute the following which will create both files.

$ make jade.min.js

Public API

    var jade = require('jade');

    // Render a string
    jade.render('string of jade', { options: 'here' });

    // Render a file
    jade.renderFile('path/to/some.jade', { options: 'here' }, function(err, html){
	    // options are optional,
	    // the callback can be the second arg
    });

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

Options

• scope Evaluation scope (this)
• self Use a self namespace to hold the locals. false by default
• locals Local variable object
• filename Used in exceptions, and required when using includes
• debug Outputs tokens and function body generated
• compiler Compiler to replace jade's default

Syntax

Line Endings

CRLF and CR are converted to LF before parsing.

Tags

A tag is simply a leading word:

html

for example is converted to <html></html>

tags can also have ids:

div#container

which would render <div id="container"></div>

how about some classes?

div.user-details

renders <div class="user-details"></div>

multiple classes? and an id? sure:

div#foo.bar.baz

renders <div id="foo" class="bar baz"></div>

div div div sure is annoying, how about:

#foo
.bar

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

`<div id="foo"></div><div class="bar"></div>`

Tag Text

Simply place some content after the tag:

p wahoo!

renders <p>wahoo!</p>.

well cool, but how about large bodies of text:

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

renders <p>foo bar baz rawr.....</p>

interpolation? yup! both types of text can utilize interpolation, if we passed { locals: { name: 'tj', email: '[e-mail]' }} to render() we can do the following:

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

outputs <div id="user">tj &lt;[e-mail]&gt;</div>

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

p \#{something}

now we have <p>#{something}</p>

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

- var html = "<script></script>"
| !{html}

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

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

or immediate tag text:

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

Tags that accept only text such as script, style, and textarea do not need the leading | character, for example:

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

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

  p.
    foo asdf
    asdf
     asdfasdfaf
     asdf
    asd.

outputs:

    <p>foo asdf
    asdf
      asdfasdfaf
      asdf
    asd
    .
    </p>

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

p .

outputs:

<p>.</p>

Comments

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

// just some paragraphs
p foo
p bar

would output

<!-- just some paragraphs -->
<p>foo</p>
<p>bar</p>

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

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

outputting

<p>foo</p>
<p>bar</p>

Block Comments

A block comment is legal as well:

  body
    //
      #content
        h1 Example

outputting

<body>
  <!--
  <div id="content">
    <h1>Example</h1>
  </div>
  -->
</body>

Jade supports conditional-comments as well, for example:

body
  //if IE
    a(href='http://www.mozilla.com/en-US/firefox/') Get Firefox

outputs:

<body>
  <!--[if IE]>
    <a href="http://www.mozilla.com/en-US/firefox/">Get Firefox</a>
  <![endif]-->
</body>

Nesting

Jade supports nesting to define the tags in a natural way:

ul
  li.first
    a(href='#') foo
  li
    a(href='#') bar
  li.last
    a(href='#') baz

Block Expansion

Block expansion allows you to create terse single-line nested tags, the following example is equivalent to the nesting example above.

  ul
    li.first: a(href='#') foo
    li: a(href='#') bar
    li.last: a(href='#') baz

Attributes

Jade currently supports '(' and ')' as attribute delimiters.

a(href='/login', title='View login page') Login

Boolean attributes are also supported:

input(type="checkbox", checked)

Boolean attributes with code will only output the attribute when true:

input(type="checkbox", checked= someValue)

Multiple lines work too:

input(type='checkbox',
  name='agreement',
  checked)

Multiple lines without the comma work fine:

input(type='checkbox'
  name='agreement'
  checked)

Funky whitespace? fine:

input(
  type='checkbox'
  name='agreement'
  checked)

Colons work:

rss(xmlns:atom="atom")

Suppose we have the user local { id: 12, name: 'tobi' } and we wish to create an anchor tag with href pointing to "/user/12" we could use regular javascript concatenation:

a(href='/user/' + user.id)= user.name

or we could use jade's interpolation:

a(href='/user/#{user.id}')= user.name

The class attribute is special-cased when an array is given, allowing you to pass an array such as bodyClasses = ['user', 'authenticated'] directly:

body(class=bodyClasses)

Doctypes

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

!!!

Will output the transitional doctype, however:

!!! 5

or

!!! html

or

doctype html

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

doctype Basic
doctype basic

Will output the html 5 doctype. Below are the doctypes defined by default, which can easily be extended:

    var doctypes = exports.doctypes = {
	    '5': '<!DOCTYPE html>',
	    'xml': '<?xml version="1.0" encoding="utf-8" ?>',
	    'default': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
	    'transitional': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
	    'strict': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">',
	    'frameset': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">',
	    '1.1': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
	    'basic': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">',
	    'mobile': '<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">'
	};

To alter the default simply change:

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

Filters

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

body
  :markdown
    Woah! jade _and_ markdown, very **cool**
    we can even link to [stuff](http://google.com)

Renders:

   <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>

Filters may also manipulate the parse tree. For example perhaps I want to bake conditionals right into jade, we could do so with a filter named conditionals. Typically filters work on text blocks, however by passing a regular block our filter can do anything it wants with the tags nested within it.

body
  conditionals:
    if role == 'admin'
      p You are amazing
    else
      p Not so amazing

Not that we no longer prefix with "-" for these code blocks. Examples of how to manipulate the parse tree can be found at ./examples/conditionals.js and ./examples/model.js, basically we subclass and re-implement visitor methods as needed. There are several interesting use-cases for this functionality above what was shown above such as transparently aggregating / compressing assets to reduce the number of HTTP requests, transparent record error reporting, and more.

Code

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

- var foo = 'bar';

This can be used for conditionals, or iteration:

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

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

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

Hell, even verbose iteration:

- 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 =:

- var foo = 'bar'
= foo
h1= foo

Which outputs bar<h1>bar</h1>. Code buffered by = is escaped by default for security, however to output unescaped return values you may use !=:

p!= aVarContainingMoreHTML

The on exception made in terms of allowing "vanilla" JavaScript, is the - each token. This takes the form of:

- each VAL[, KEY] in OBJ

An example iterating over an array:

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

outputs:

<li>one</li>
<li>two</li>
<li>three</li>

iterating an object's keys and values:

- var obj = { foo: 'bar' }
- each val, key in obj
  li #{key}: #{val}

would output <li>foo: bar</li>

You can also nest these!

- each user in users
  - each role in user.roles
    li= role

When a property is undefined, Jade will output an empty string. For example:

textarea= user.signature

when undefined would normally output "undefined" in your html, however recent versions of Jade will simply render:

<textarea></textarea>

Includes

Includes allow you to statically include chunks of Jade which lives in a separate file. The classical example is including a header and footer. Suppose we have the following directory structure:

 ./layout.jade
 ./includes/
   ./head.jade
   ./tail.jade

and the following layout.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 the filename option given to layout.jade, which should be an absolute path to this file, however Express and the renderFile() method do this for you. Include then parses these files, and injects the AST produced to render what you would expect:

<html>
  <head>
    <title>My Site</title>
    <script src="/javascripts/jquery.js">
    </script><script src="/javascripts/app.js"></script>
  </head>
  <body>
    <h1>My Site</h1>
    <p>Welcome to my super lame site.</p>
    <div id="footer">
      <p>Copyright>(c) foobar</p>
    </div>
  </body>
</html>

Mixins

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

  mixin list
    ul
      li foo
      li bar
      li baz

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

  h2 Groceries
  mixin list

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

  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:

<div class="user">
  <h2>tj</h2>
  <ul class="pets">
    <li>tobi</li>
    <li>loki</li>
    <li>jane</li>
    <li>manny</li>
  </ul>
</div>

bin/jade

Output html to stdout:

jade < my.jade > my.html

Generate examples/*.html:

jade examples/*.jade

Pass options:

jade examples/layout.jade --options '{ locals: { title: "foo" }}'

Usage info:

Usage: jade [options]
            [path ...]
            < in.jade > out.jade  
Options:
  -o, --options <str>  JavaScript options object passed
  -h, --help           Output help information
  -w, --watch          Watch file(s) or folder(s) for changes and re-compile
  -v, --version        Output jade version
  --out <dir>          Output the compiled html to <dir>

License

(The MIT License)

Copyright (c) 2009-2010 TJ Holowaychuk <[e-mail]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.