Fork me on GitHub

Tutorial

Introduction

This tutorial is a work in progress. Once it's finished it will become a fully fledged getting started guide.

Welcome to the Jade templating engine. Jade is designed primarily for server side templating in node.js, however it can be used in many other environments. It is only intended to produce XML like documents (HTML, RSS etc.) so don't use it to create plain text/markdown/CSS/whatever documents.

This tutorial will take you through:

  • The Basics
    • Creating Simple Tags
    • Putting Text Inside your Tags
    • Attributes
    • IDs and Classes
  • JavaScript
    • Outputing Text
    • Setting Attributes
    • Loops and Conditionals
  • Advanced Templating
    • Extends & Blocks
    • Includes
    • Mixins
    • Filters

The Basics

Jade can be used just as a short hand for HTML. This section covers everything you need to know to do that.

Creating Simple Tags

Jade is whitespace sensitive, so there's no need to close your tags; Jade does that for you. You can also nest tags within other tags just by indenting them.

div
  address
  i
  strong
<div>
  <address></address>
  <i></i>
  <strong></strong>
</div>

Putting Text Inside your Tags

By default, the content of a tag is parsed as more jade. There are three ways to put plain text inside a tag.

h1 Welcome to Jade
p
  | Text can be included in a number of
  | different ways.
p.
  This way is shortest if you need big
  blocks of text spanning multiple
  lines.
<h1>Welcome to Jade</h1>
<p>Text can be included in a number of
   different ways.</p>
<p>This way is shortest if you need big
   blocks of text spanning multiple
   lines.</p>

Adding Attributes to your Tags

To add attributes you put them in parentheses after the tag name, separated by an optional comma.

h1(id="title") Welcome to Jade
button(class="btn", data-action="bea").
  Be Awesome
<h1 id="title">Welcome to Jade</h1>
<button class="btn" data-action="bea">
  Be Awesome
</button>

IDs and Classes

Adding IDs and Classes is super common, so we made it super easy to do by adding a simple short hand. The syntax is just like that of CSS selectors:

h1#title Welcome to Jade
button.btn(data-action="bea") Awesome
<h1 id="title">Welcome to Jade</h1>
<button class="btn" data-action="bea">
  Awesome
</button>

JavaScript

Jade is much more than just a short hand for HTML. It also has features that let you build dynamic templates.

Outputing Text

You can output raw text from JavaScript variables. Jade will also helpfully filter the text for you so it's safe from nasty HTML injection attacks.

var jade = require('jade');
var fn = jade.compile(jadeTemplate);
var htmlOutput = fn({
  maintainer: {
    name: 'Forbes Lindesay',
    twitter: '@ForbesLindesay',
    blog: 'forbeslindesay.co.uk'
  }
});
h1
  | Maintainer:
  = ' ' + maintainer.name
table
  tr
    td Twitter
    td= maintainer.twitter
  tr
    td Blog
    td= maintainer.blog
<h1>Maintainer: Forbes Lindesay</h1>
<table>
  <tr>
    <td>Twitter</td>
    <td>@ForbesLindesay</td>
  </tr>
  <tr>
    <td>Blog</td>
    <td>forbeslindesay.co.uk</td>
  </tr>
</table>

If you don't want Jade to filter your output, use != instead of =.

Setting Attributes

Setting attributes to JavaScript values requires no extra work:

h1(name=maintainer.name)
  | Maintainer:
  = ' ' + maintainer.name
table
  tr
    td(style='width: '+(100/2)+'%').
      Twitter
    td= maintainer.twitter
  tr
    td(style='width: '+(100/2)+'%').
      Blog
    td= maintainer.blog
<h1 name="Forbes Lindesay">
  Maintainer: Forbes Lindesay
</h1>
<table>
  <tr>
    <td style="width: 50%">Twitter</td>
    <td>@ForbesLindesay</td>
  </tr>
  <tr>
    <td style="width: 50%">Blog</td>
    <td>forbeslindesay.co.uk</td>
  </tr>
</table>

Loops and Conditionals

You can use if statements to decide what to display depending on various factors - maybe a user is logged in or not, or some content exists or not, or a combination of factors.

Jade's if statements are almost exactly like those present in JavaScript, except the parentheses are optional, and you don't need braces!

- var user = { name: 'John' }
if user
  div.welcomebox
    // Filtered inline output
    p.
      Welcome, #{user.name}
else
  div.loginbox
    form(name="login", action="/login", method="post")
      input(type="text", name="user")
      input(type="password", name="pass")
      input(type="submit", value="login")
<div class="welcomebox">
  <!-- Filtered inline output-->
  <p>Welcome, John</p>
</div>

Advanced Templating

Extends & Blocks

Includes

Mixins

Filters

To Be Continued....

The jade source for this file can be viewed (and edited/improved) on GitHub