====== Getting started ======

===== Installing Jade =====
To use Jade, you must first have Node.js installed on your system. On Windows and MacOS, you can use an [[http://nodejs.org/download/|installer]]; on Linux, you should be able to [[https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager|use your package manager]]((See http://lovingthepenguin.blogspot.com/2013/10/node-no-such-file-or-directory.html for a potential gotcha on Debian-based systems.)).

Once you have Node.js installed, you have the choice of installing the Jade module so it's available system-wide or only for a particular project. To make it available system-wide, open a terminal and enter: <code>npm install jade -g</code>

When I am learning new Node.js modules, I prefer to install them on a per-project basis. To do this, open a terminal in your project directory (or navigate to the directory) and enter: <code>npm install jade</code>

When this is done you should see a ''node_modules'' subdirectory inside your project directory. Inside ''node_modules'' will be the Jade modules as well as any other modules Jade depends on.

===== Creating an HTML fragment =====

==== Rendering Jade strings to HTML ====

The first thing we are going to do is use Jade to produce an HTML fragment from a string literal. This is done with the ''jade.render'' method.
<file javascript renderFragment.js >
var jade = require('jade');

// Render an HTML fragment from a string literal written in Jade.
var htmlFrag = jade.render('p Hello, world');

console.log(htmlFrag);
</file>

output: <code><p>Hello, world</p></code>

==== Compiling Jade strings into functions ====

You can use the ''jade.compile'' method to create a function that when called will return the converted Jade.
<file javascript compileFragment.js>
var jade = require('jade');

// Compile a function that produces an HTML fragment from a string
// literal written in Jade.
var frag = jade.compile('p Hello, world');

// Render stuff.
var htmlFrag = frag();

console.log(htmlFrag);
</file>

output: <code><p>Hello, world</p></code>

==== Rendering a file full of Jade ====

In a lot of cases, you will want to render code that is stored in a file rather than in a string literal or variable. You can do that with the ''jade.renderFile'' method.

<file jade myFrag.jade>
h1 Hello, there!
p Nice to meet you.
</file>

<file javascript renderFragmentFile_1.js>
var jade = require('jade');

// Render an HTML fragment from a file written in Jade.
var htmlFrag = jade.renderFile('myFrag.jade');

console.log(htmlFrag);
</file>

output: <code><h1>Hello, there!</h1><p>Nice to meet you.</p></code>

=== Adding options ===

The above produces valid HTML, but it's hard to read. To make the output human-readable, we can pass ''jade.renderFile'' an options object with its ''pretty'' property set to true. (The options argument can be provided to the ''jade.render'' and ''jade.compile'' methods as well.)

<file javascript renderFragmentFile_2.js>
var jade = require('jade');

options = {
    pretty: true
};

// Render an HTML fragment from a file written in Jade.
var htmlFrag = jade.renderFile('myFrag.jade', options);

console.log(htmlFrag);
</file>

output: <code><h1>Hello, there!</h1>
<p>Nice to meet you.</p></code>

=== Using the callback function ===

You can (and should) also take anvantage of the callback that you can pass to ''jade.renderFile'' to handle errors:
<file javascript renderFragmentFile_3.js>
var jade = require('jade');

options = {
    pretty: true
};

// Render an HTML fragment from a file written in Jade.
// Use callback to trap errors.
var htmlFrag = jade.renderFile('myFrag.jade', options, function (err, html) {
        if (err) {
           throw(err);
        }
        return html;
    });
    
console.log(htmlFrag);
</file>

==== Writing output to a file ====
To write the output created to a file, you'll need to use Node.js' ''fs'' module.

<file javascript convertFragment.js>
var jade = require('jade');
var fs = require('fs');

options = {
    pretty: true
};

// Render an HTML fragment from a file written in Jade.
var htmlFrag = jade.renderFile('myFrag.jade', options, function(err, html) {
        if (err) {
           throw(err);
        }
        return html;
    });

// Write HTML fragment to a file.
fs.writeFile('myFrag.html', htmlFrag, function(err) {
    if (err) {
        throw(err);
    }
});
</file>

output:<code bash>
$ cat myFrag.html 

<h1>Hello, there!</h1>
<p>Nice to meet you.</p>
</code>

===== Creating web pages =====

In this section, we will use Jade to build a simple but complete web page. It will serve as an introduction to fundamental Jade language concepts.

<file jade myPage.jade>
doctype html
html
    head
        title A Simple Site
    body
        h1 Hello there!
        p Nice to meet you.
</file>

<file javascript buildMyPage.js>
var jade = require('jade');
var fs = require('fs');

options = {
    pretty: true
};

// Render an HTML page from a file written in Jade.
var html = jade.renderFile('myPage.jade', options, function(err, html) {
        if (err) {
           throw(err);
        }
        return html;
    });

// Write HTML to a file.
fs.writeFile('myPage.html', html, function(err) {
    if (err) {
        throw(err);
    }
});
</file>

output:<code>
$ cat myPage.html 
<!DOCTYPE html>
<html>
  <head>
    <title>A Simple Site</title>
  </head>
  <body>
    <h1>Hello there!</h1>
    <p>Nice to meet you.</p>
  </body>
</html>
</code>

The basic idea is that Jade uses a shorthand HTML syntax where indentation is used to nest elements.

This should be enough to make you comfortable reading the [[http://jade-lang.com/reference/|Jade Language Reference]], after which you should be able to compose entire web pages.