API 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!');

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
• 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 along with the Pug runtime.

• 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 along with the Pug runtime.

• 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("");
}

Be sure to send the Pug runtime (node_modules/pug/runtime.js) to the client in addition to the template that you just compiled.

<!DOCTYPE html>
<html>
  <head>
    <script src="/runtime.js"></script>
    <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.

Deprecated

This property has been deprecated in favor of the filters option.