-Robust, elegant, feature rich template engine for Node.js

Rename from "Jade"

Heavily influenced by Haml and implemented with JavaScript.


This project was formerly known as "Jade".
However, it was revealed to us that "Jade" is a registered trademark;
as a result, a rename was needed.

After some discussion among the maintainers,
"Pug" was chosen as the new name for this project.

Getting Started

Installation

Pug is available via npm:

$ npm install pug

Overview

The general rendering process of Pug is simple. pug.compile() will compile the Pug source
code into a JavaScript function that takes a data object (called “locals”) as an argument. Call
that resultant function with your data, and voilà!, it will return a string of HTML rendered with
your data.

The compiled function can be re-used, and called with different sets of data.

//- template.pug
p #{name}'s Pug source code!
                
const pug = require('pug');

// Compile the source code
const compiledFunction = pug.compileFile('template.pug');

// Render a set of data
console.log(compiledFunction({
  name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

// Render another set of data
console.log(compiledFunction({
  name: 'Forbes'
}));
// "
Forbes's Pug source code!
"

Pug also provides the pug.render() family of functions that combine compiling and rendering
into one step. However, the template function will be re-compiled every time render is called,
which might impact performance. Alternatively, you can use the cache option with render,
which will automatically store the compiled function into an internal cache.

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"
Express Integration

Pug fully integrates with Express, a popular Node.js web framework, as a supported view
engine. Check out Express’s excellent guide for how to integrate Pug with Express.

Production Defaults

In Express, the environmental variable NODE_ENV is designed to inform the web application of
the execution environment: whether it is in development or in production. Express and Pug
automatically modify the defaults of a few options in production environment, to provide a
better out-of-the-box experience for users.


Specifically, when process.env.NODE_ENV is set to 'production', and Pug is used with
Express, the compileDebug option is false by default, while the cache option is true.


To override the defaults for compileDebug and cache, you can set the respective property in
app.locals or res.locals objects to true or false. The cache option can also be
overriden through Express’s app.disable/enable('view cache').


For more details, check Express’s API reference.

Reference

This page details how to render Pug using the JavaScript API.

Tip

Pug is available in your Web browser’s console! To test drive Pug’s API, as documented on this page, try entering:

pug.render('p Hello world!');
Attributes

Tag attributes look similar to HTML (with optional commas), but their values are just regular
JavaScript.

(NOTE: Examples on this page use the pipe character (|) for whitespace control.)

a(href='//google.com') Google
|
|
a(class='button' href='//google.com') Google
|
|
a(class='button', href='//google.com') Google

Normal JavaScript expressions work fine, too:


- var authenticated = true
body(class=authenticated ? 'authed' : 'anon')

(body class="authed">(/body>

Multiline Attributes

If you have many attributes, you can also spread them across many lines:

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"
const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

If your JavaScript runtime supports ES2015 template strings (including Node.js/io.js 1.0.0 and
later), you can use that syntax for attributes. This is really useful for attributes with really long
values:

const pug = require('pug');
// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"
const pug = require('pug');
// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Quoted Attributes

If your attribute name contains odd characters that might interfere with JavaScript syntax, either
quote it using "" or '', or use commas to separate different attributes. Examples of such
characters include [] and () (frequently used in Angular 2).

//- In this case, `(click)` is treated as a
//- function call instead of a attribute name,
/- resulting in the unusual error.
div(class='div-class' (click)='play()')
index.pug:4:11
2| //- function call instead of a attribute name,
3| //- resulting in the unusual error.
> 4| div(class='div-class' (click)='play()')
-----------------^
                
Syntax Error: Assigning to rvalue
div(class='div-class', (click)='play()')
div(class='div-class' '(click)'='play()')

Attribute Interpolation

Caution

Previous versions of Pug/Jade supported an interpolation syntax such as:

a(href="/#{url}")Link

This syntax is no longer supported. Alternatives are found below. (Check our migration guide for more
information on other incompatibilities between Pug v2 and previous versions.)

Case

The case statement is a shorthand for JavaScript’s switch statement. It takes the following
form:


Case Fall Through 

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

If your JavaScript runtime supports ES2015 template strings (including Node.js/io.js 1.0.0 and
later), you can use that syntax for attributes. This is really useful for attributes with really long
values:

Block Expansion 

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

If your JavaScript runtime supports ES2015 template strings (including Node.js/io.js 1.0.0 and
later), you can use that syntax for attributes. This is really useful for attributes with really long
values:

Code

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');
            
// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
  name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Unbuffered Code

Unbuffered code starts with -. It does not directly add anything to the output.

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');
            
 // Compile template.pug, and render a set of data
 console.log(pug.renderFile('template.pug', {
  name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Unescaped Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs the
result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

Comments

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Conditionals

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

   // Compile template.pug, and render a set of data
   console.log(pug.renderFile('template.pug', {
     name: 'Timothy'
   }));
   // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Doctype

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

   // Compile template.pug, and render a set of data
   console.log(pug.renderFile('template.pug', {
     name: 'Timothy'
   }));
   // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Filters

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

   // Compile template.pug, and render a set of data
   console.log(pug.renderFile('template.pug', {
     name: 'Timothy'
   }));
   // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');
     // Compile template.pug, and render a set of data
     console.log(pug.renderFile('template.pug', {
       name: 'Timothy'
     }));
     // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Includes

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

  // Compile template.pug, and render a set of data
  console.log(pug.renderFile('template.pug', {
    name: 'Timothy'
  }));
  // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Template Inheritance

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

   // Compile template.pug, and render a set of data
   console.log(pug.renderFile('template.pug', {
     name: 'Timothy'
   }));
   // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

     // Compile template.pug, and render a set of data
     console.log(pug.renderFile('template.pug', {
       name: 'Timothy'
     }));
     // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Interpolation

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');
    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

   // Compile template.pug, and render a set of data
   console.log(pug.renderFile('template.pug', {
     name: 'Timothy'
   }));
   // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Iteration

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

  // Compile template.pug, and render a set of data
  console.log(pug.renderFile('template.pug', {
    name: 'Timothy'
  }));
  // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');
     // Compile template.pug, and render a set of data
     console.log(pug.renderFile('template.pug', {
       name: 'Timothy'
     }));
     // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Mixins

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

 // Compile template.pug, and render a set of data
 console.log(pug.renderFile('template.pug', {
   name: 'Timothy'
 }));
 // "
Timothy's Pug source code!
"

Unbuffered Code

Buffered Code

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

    // Compile template.pug, and render a set of data
    console.log(pug.renderFile('template.pug', {
      name: 'Timothy'
    }));
    // "
Timothy's Pug source code!
"

Unescaped Buffered Code

Plain Text

Pug provides four ways of getting plain text — that is, any code or text content that should go,
mostly unprocessed, directly into the rendered HTML. They are useful in different situations.

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

Pug allows you to write inline JavaScript code in your templates. There are three types of code:
Unbuffered, Buffered, and Unescaped Buffered.

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Block Expansion

Self-Closing Tags

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Rendered Whitespace

Tags

By default, text at the start of a line (or after only white space) represents an HTML tag.
Indented tags are nested, creating the tree structure of HTML.

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Block Expansion

Self-Closing Tags

Unescaped buffered code starts with !=. It evaluates the JavaScript expression and outputs
the result. Unescaped buffered code does not perform any escaping, so is unsafe for user input:

const pug = require('pug');

// Compile template.pug, and render a set of data
console.log(pug.renderFile('template.pug', {
name: 'Timothy'
}));
// "
Timothy's Pug source code!
"

Rendered Whitespace

Community Support

Pug is a community run open source project, and we’d love to help you get started.

Stack Overflow

For crowdsourced technical questions from expert Pug devs in our community. Also frequented by the Pug core team.

Post a question

Twitter

Receive the latest news on Pug

Follow us

GitHub

We use GitHub issues exclusively as a bugs and feature requests tracker. If you think you have
found a bug, or have a new feature idea, please start by making sure it hasn’t already been
reported or fixed. You can search through existing issues and pull requests to see if someone
has reported one similar to yours.

Open an issue

Entreprise Support

Tidelift subscription

Pug and the maintainers of thousands of other packages are working with Tidelift to deliver
one enterprise subscription that covers all of the open-source you use.


If you want the flexibility of open-source and the confidence of commercial-grade software, this
is worth looking at.


The Tidelift Subscription manages your dependencies for you:


  • Get the tools you need to continuously catalog and understand the open-source software that your application depends on.
  • Your subscription helps pay the open-source community maintainers of the packages you use, to ensure they meet the standards you require.
  • Address issues proactively, with tools that scan for new security, licensing, and maintenance issues, and alert participating open-source maintainers so they can resolve them on your behalf.
  • Tidelift helps measure and improve your open-source dependencies’ health – which improves your app’s health – and gives a shortlist of high-impact steps your team can take to improve them even more.
  • Get commercial assurances that don’t come for free with open-source packages, such as intellectual property indemnification and support under a service level agreement. You expect these guarantees from proprietary software, and you can get them when using open-source as well.

The end result? All of the capabilities you expect from commercial-grade software, for the full
breadth of open-source you use. That means less time grappling with esoteric open-source
trivia, and more time building your own applications – and your business.


Get more details


Request a demo

Custom Work

Tweak Pug to meet specific requirements. Give us a summary of your needs and we’ll help you if
we can.


Note that work must be Pug related. We don’t accept general development work. Our
contracting price is $200/hour or $1,500/day.


Send us an email

Summary

You have reached the end of the documentation! Of course, this is a layout exercise, and some chapters have been paste/colled for the sake of conciseness.


All the documentation on this page is taken from PugJs


Certification Project, Technical Documentation Page, freeCodeCamp(🔥)
Powered by z-bj