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.
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 contentMixins
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'])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 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 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.
Jade is a high performance template engine heavily influenced by Haml and implemented with JavaScript for node. For discussion join the Google Group.
Jade version 0.31.0 deprecated implicit text only support for scripts and styles. To fix this all you need to do is add a . character after the script or style tag.
It is hoped that this change will make Jade easier for newcomers to learn without affecting the power of the language or leading to excessive verboseness.
If you have a lot of Jade files that need fixing you can use fix-jade to attempt to automate the process.
You can test drive Jade online here.
eachvia npm:
$ npm install jade
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. However each release builds these for you.
$ make jade.min.js
By default Jade instruments templates with line number statements such as __.lineno = 3 for debugging purposes. When used in a browser it's useful to minimize this boiler plate, you can do so by passing the option { compileDebug: false }. The following template
p Hello #{name}
Can then be as small as the following generated function:
function anonymous(locals, attrs, escape, rethrow) {
var buf = [];
with (locals || {}) {
var interp;
buf.push('\n<p>Hello ' + escape((interp = name) == null ? '' : interp) + '\n</p>');
}
return buf.join("");
}
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
via jade.attrs, jade.escape etc.
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<p>Hello ' + escape((interp = name) == null ? '' : interp) + '\n</p>');
}
return buf.join("");
}
var jade = require('jade');
// Compile a function
var fn = jade.compile('string of jade', options);
fn(locals);
self Use a self namespace to hold the locals (false by default)locals Local variable objectfilename Used in exceptions, and required when using includesdebug Outputs tokens and function body generatedcompiler Compiler to replace jade's defaultcompileDebug When false no debug instrumentation is compiledpretty Add pretty-indentation whitespace to output (false by default)CRLF and CR are converted to LF before parsing.
### TagsA 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>
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 { name: 'tj', email: 'tj@vision-media.ca' } to the compiled function we can do the following:
#user #{name} <#{email}>
outputs <div id="user">tj <tj@vision-media.ca></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]')
As an alternative, we may use a trailing . 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 trailing . followed by a space, which although is ignored by the Jade parser, tells Jade that this period is a literal:
p .
outputs:
<p>.</p>
It should be noted that text blocks should be doubled escaped. For example if you desire the following output.
<p>foo\bar</p>
use:
p.
foo\\bar
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>
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:
head
//if lt IE 8
script(src='/ie-sucks.js')
outputs:
<head>
<!--[if lt IE 8]>
<script src="/ie-sucks.js"></script>
<![endif]-->
</head>
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 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
The case statement takes the following form:
html
body
friends = 10
case friends
when 0
p you have no friends
when 1
p you have a friend
default
p you have #{friends} friends
Block expansion may also be used:
friends = 5
html
body
case friends
when 0: p you have no friends
when 1: p you have a friend
default: p you have #{friends} friends
Jade currently supports ( and ) as attribute delimiters.
a(href='/login', title='View login page') Login
When a value is undefined or null the attribute is not added,
so this is fine, it will not compile something="null".
div(something=null)
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, which I added because everyone using Ruby or CoffeeScript seems to think this is legal js..:
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)
Inline html is fine, we can use the pipe syntax to write arbitrary text, in this case some html:
html
body
| <h1>Title</h1>
| <p>foo bar baz</p>
Or we can use the trailing . to indicate to Jade that we
only want text in this block, allowing us to omit the pipes:
html
body.
<h1>Title</h1>
<p>foo bar baz</p>
Both of these examples yield the same result:
<html><body><h1>Title</h1>
<p>foo bar baz</p>
</body></html>
The same rule applies for anywhere you can have text in jade, raw html is fine:
html
body
h1 User <em>#{name}</em>
To add a doctype simply use !!!, or doctype followed by an optional value:
!!!
or
doctype
Will output the html 5 doctype, however:
!!! transitional
Will output the transitional doctype.
Doctypes are case-insensitive, so the following are equivalent:
doctype Basic
doctype basic
it's also possible to simply pass a doctype literal:
doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"
yielding:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN">
Below are the doctypes defined by default, which can easily be extended:
var doctypes = exports.doctypes = {
'5': '<!DOCTYPE html>',
'default': '<!DOCTYPE html>',
'xml': '<?xml version="1.0" encoding="utf-8" ?>',
'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 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>
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
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:
- 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:
if foo == 'bar'
ul
li yay
li foo
li worked
else
p oh no! didnt work
Along with vanilla JavaScript Jade also supports a subset of
constructs that allow you to create more designer-friendly templates,
one of these constructs is each, taking the form:
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 array with index:
items = ["one", "two", "three"]
each item, i in items
li #{item}: #{i}
outputs:
<li>one: 0</li>
<li>two: 1</li>
<li>three: 2</li>
iterating an object's keys and values:
obj = { foo: 'bar' }
each val, key in obj
li #{key}: #{val}
would output <li>foo: bar</li>
Internally Jade converts these statements to regular
JavaScript loops such as users.forEach(function(user){,
so lexical scope and nesting applies as it would with regular
JavaScript:
each user in users
each role in user.roles
li= role
You may also use for if you prefer:
for user in users
for role in user.roles
li= role
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:
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:
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)):
for user in users
unless user.isAnonymous
p
| Click to view
a(href='/users/' + user.id)= user.name
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.
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".
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.
extends regular-layout
block content
.sidebar
block sidebar
p nothing
.primary
block primary
p nothing
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:
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:
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:
extends layout
append head
script(src='/vendor/three.js')
script(src='/game.js')
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:
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
does 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>
As mentioned include can be used to include other content
such as html or css. By providing an extension, Jade will
read that file in, apply any filter matching the file's
extension, and insert that content into the output.
html
head
//- css and js have simple filters that wrap them in
<style> and <script> tags, respectively
include stylesheet.css
include script.js
body
//- "markdown" files will use the "markdown" filter
to convert Markdown to HTML
include introduction.markdown
//- html files have no filter and are included verbatim
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 if head.jade contains:
head
script(src='/jquery.js')
We may append values by providing a block to include head
as shown below, adding the two scripts.
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:
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.
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.
users = [{ name: 'Tobi', occupation: 'Ferret' }]
each user in users
.user
include user
yielding:
<div class="user">
<h1>Tobi</h1>
<p>Ferret</p>
</div>
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:
each person in users
.user
user = person
include user
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>
Suppose we have the following 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 to rethrow() which constructs
a useful message relative to the initial Jade input.
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('<h1');
buf.push(attrs({ "class": ('title') }));
buf.push('>');
buf.push('' + escape((interp = title) == null ? '' : interp) + '');
buf.push('</h1>');
__.lineno = 3;
buf.push('<p>');
buf.push('Just an example');
buf.push('</p>');
}
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.js file 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.
function anonymous(locals) {
var attrs = jade.attrs, escape = jade.escape;
var buf = [];
with (locals || {}) {
var interp;
var title = 'yay'
buf.push('<h1');
buf.push(attrs({ "class": ('title') }));
buf.push('>');
buf.push('' + escape((interp = title) == null ? '' : interp) + '');
buf.push('</h1>');
buf.push('<p>');
buf.push('Just an example');
buf.push('</p>');
}
return buf.join("");
}
Below is an example Makefile used to compile pages/*.jade
into pages/*.html files by simply executing make.
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.)
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:
$ watch make
or you use the watch option below:
## jade(1)
Usage: jade [options] [dir|file ...]
Options:
-h, --help output usage information
-V, --version output the version number
-O, --obj <str> javascript options object
-o, --out <dir> output the compiled html to <dir>
-p, --path <path> filename used to resolve includes
-P, --pretty compile pretty html output
-c, --client compile function for client-side runtime.js
-D, --no-debug compile without debugging (smaller functions)
-w, --watch watch files for changes and automatically re-render
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
(The MIT License)
Copyright (c) 2009-2010 TJ Holowaychuk <tj@vision-media.ca>
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.
FAQs
A clean, whitespace-sensitive template language for writing HTML
The npm package jade receives a total of 137,634 weekly downloads. As such, jade popularity was classified as popular.
We found that jade demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.