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 andextend
\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 tofalse
. - 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 writingvariable
you will have to writeself.variable
to access a property of the locals object. Defaults tofalse
. - 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 torender
functions. Defaults tofalse
. - inlineRuntimeFunctions: boolean
- Inline runtime functions instead of
require
-ing them from a shared version. ForcompileClient
functions, the default istrue
(so that one does not have to include the runtime). For all other compilation or rendering types, the default isfalse
. - 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("");
}
<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.
Deprecated
This property has been deprecated in favor of the filters
option.