API Reference

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

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

Options ¶

All API methods accept the following set of options:

filename: string

The name of the file being compiled. Used in exceptions, and required for relative include\s and extend\s. Defaults to 'Pug'.

basedir: string

The root directory of all absolute inclusion.

doctype: string

If the doctype is not specified as part of the template, you can specify it here. It is sometimes useful to get self-closing tags and remove mirroring of boolean attributes. See doctype documentation for more information.

pretty: boolean | string

[Deprecated.] Adds whitespace to the resulting HTML to make it easier for a human to read using '  ' as indentation. If a string is specified, that will be used as indentation instead (e.g. '\t'). We strongly recommend against using this option. Too often, it creates subtle bugs in your templates because of the way it alters the interpretation and rendering of whitespace, and so this feature is going to be removed. Defaults to false.

filters: object

Hash table of custom filters. Defaults to undefined.

self: boolean

Use a self namespace to hold the locals. It will speed up the compilation, but instead of writing variable you will have to write self.variable to access a property of the locals object. Defaults to false.

debug: boolean

If set to true, the tokens and function body are logged to stdout.

compileDebug: boolean

If set to true, the function source will be included in the compiled template for better error messages (sometimes useful in development). It is enabled by default, unless used with Express in production mode.

globals: Array<string>

Add a list of global names to make accessible in templates.

cache: boolean

If set to true, compiled functions are cached. filename must be set as the cache key. Only applies to render functions. Defaults to false.

inlineRuntimeFunctions: boolean

Inline runtime functions instead of require-ing them from a shared version. For compileClient functions, the default is true (so that one does not have to include the runtime). For all other compilation or rendering types, the default is false.

name: string

The name of the template function. Only applies to compileClient functions. Defaults to 'template'.

Methods ¶

pug.compile(source, ?options) ¶

Compile a Pug template to a function, which can be rendered multiple times with different locals.

source: string

The source Pug template to compile

options: ?options

An options object

returns: function

A function to generate the HTML from an object containing locals

var pug = require('pug');

// Compile a function
var fn = pug.compile('string of pug', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileFile(path, ?options) ¶

Compile a Pug template from a file to a function, which can be rendered multiple times with different locals.

path: string

The path to a Pug file

options: ?options

An options object

returns: function

A function to generate the HTML from an object containing locals

var pug = require('pug');

// Compile a function
var fn = pug.compileFile('path to pug file', options);

// Render the function
var html = fn(locals);
// => '<string>of pug</string>'

pug.compileClient(source, ?options) ¶

Compile a Pug template to a string of JavaScript, which can be used client side.

source: string

The Pug template to compile

options: ?options

An options object

returns: string

A string of JavaScript representing a function

var pug = require('pug');

// Compile a function
var fn = pug.compileClient('string of pug', options);

// Render the function
var html = fn(locals);
// => 'function template(locals) { return "<string>of pug</string>"; }'

pug.compileClientWithDependenciesTracked(source, ?options) ¶

Same as compileClient, except that this method returns an object of the form:

{
  'body': 'function (locals) {...}',
  'dependencies': ['filename.pug']
}

You should only use this method if you need dependencies to implement something like watching for changes to the Pug files.

pug.compileFileClient(path, ?options) ¶

Compile a Pug template file to a string of JavaScript that can be used client side.

path: string

The path to a Pug file

options: ?options

An options object

options.name: string

If you pass a .name property on the options object, it will be used as the name of your client side template function.

returns: string

A JavaScript function body.

First, our template file.

h1 This is a Pug template
h2 By #{author}

Then, we compile the Pug file into a function string.

var fs = require('fs');
var pug = require('pug');

// Compile the template to a function string
var jsFunctionString = pug.compileFileClient('/path/to/pugFile.pug', {name: "fancyTemplateFun"});

// Maybe you want to compile all of your templates to a templates.js file and serve it to the client
fs.writeFileSync("templates.js", jsFunctionString);

Here’s what the output function string looks like (written to templates.js).

function fancyTemplateFun(locals) {
  var buf = [];
  var pug_mixins = {};
  var pug_interp;

  var locals_for_with = (locals || {});

  (function (author) {
    buf.push("<h1>This is a Pug template</h1><h2>By "
      + (pug.escape((pug_interp = author) == null ? '' : pug_interp))
      + "</h2>");
  }.call(this, "author" in locals_for_with ?
    locals_for_with.author : typeof author !== "undefined" ?
      author : undefined)
  );

  return buf.join("");
}

<!DOCTYPE html>
<html>
  <head>
    <script src="/templates.js"></script>
  </head>

  <body>
    <h1>This is one fancy template.</h1>

    <script type="text/javascript">
      var html = window.fancyTemplateFun({author: "enlore"});
      var div = document.createElement("div");
      div.innerHTML = html;
      document.body.appendChild(div);
    </script>
  </body>
</html>

pug.render(source, ?options, ?callback) ¶

source: string

The source Pug template to render

options: ?options

An options object, also used as the locals object

callback: ?function

Node.js-style callback receiving the rendered results. This callback is called synchronously.

returns: string

The resulting HTML string

var pug = require('pug');

var html = pug.render('string of pug', options);
// => '<string>of pug</string>'

pug.renderFile(path, ?options, ?callback) ¶

path: string

The path to the Pug file to render

options: ?options

An options object, also used as the locals object

callback: ?function

Node.js-style callback receiving the rendered results. This callback is called synchronously.

returns: string

The resulting HTML string

var pug = require('pug');

var html = pug.renderFile('path/to/file.pug', options);
// ...

Properties ¶

pug.filters ¶

A hash table of custom filters.

This object has the same semantics as the filters option, but applies globally to all Pug compilation. When a filter is present in both pug.filters and options.filters, the filters option takes precedence.