0
# Pug
1

2
Pug is a high-performance template engine for Node.js and browsers that transforms clean, whitespace-sensitive syntax into HTML. It provides a concise and intuitive way to write HTML templates using indentation-based structure, element classes and IDs via CSS selector syntax, JavaScript expressions for dynamic content, conditionals and loops for logic, mixins for reusable components, and includes/extends for template composition.
3

4
## Package Information
5

6
- **Package Name**: pug
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pug`
10

11
## Core Imports
12

13
```javascript
14
const pug = require("pug");
15
```
16

17
For ES modules:
18

19
```javascript
20
import pug from "pug";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const pug = require("pug");
27

28
// Compile a template from string
29
const template = pug.compile('p Hello #{name}!');
30
const html = template({ name: 'World' });
31
// Result: <p>Hello World!</p>
32

33
// Render directly from string
34
const html2 = pug.render('h1 Welcome to #{site}', { site: 'Pug' });
35
// Result: <h1>Welcome to Pug</h1>
36

37
// Render from file
38
const html3 = pug.renderFile('template.pug', { user: 'Alice' });
39
```
40

41
## Architecture
42

43
Pug is built around several key components:
44

45
- **Compilation API**: Functions to compile templates into reusable functions (`compile`, `compileFile`)
46
- **Rendering API**: Direct template-to-HTML conversion (`render`, `renderFile`)
47
- **Client-Side Compilation**: Generate JavaScript code for browser use (`compileClient`, `compileFileClient`)
48
- **Template Caching**: Built-in caching system for improved performance
49
- **Plugin System**: Extensible architecture supporting custom processing stages
50
- **Express Integration**: Native support for Express.js view engine
51

52
## Capabilities
53

54
### Template Compilation
55

56
Core compilation functionality for transforming Pug templates into executable JavaScript functions. Essential for production applications requiring maximum performance.
57

58
```javascript { .api }
59
/**
60
 * Compile a Pug template string into a function
61
 * @param str - Pug template source code
62
 * @param options - Compilation options
63
 * @returns Template function that accepts locals and returns HTML string
64
 */
65
function compile(str, options);
66

67
/**
68
 * Compile a Pug template file into a function
69
 * @param path - Path to Pug template file
70
 * @param options - Compilation options
71
 * @returns Template function with caching support
72
 */
73
function compileFile(path, options);
74
```
75

76
[Template Compilation](./compilation.md)
77

78
### Template Rendering
79

80
Direct template-to-HTML conversion for simple use cases and development environments. Combines compilation and execution in a single step.
81

82
```javascript { .api }
83
/**
84
 * Render a Pug template string directly to HTML
85
 * @param str - Pug template source code
86
 * @param options - Rendering options including locals
87
 * @param fn - Optional callback for async operation
88
 * @returns HTML string (sync) or calls callback (async)
89
 */
90
function render(str, options, fn);
91

92
/**
93
 * Render a Pug template file directly to HTML
94
 * @param path - Path to Pug template file
95
 * @param options - Rendering options including locals
96
 * @param fn - Optional callback for async operation
97
 * @returns HTML string (sync) or calls callback (async)
98
 */
99
function renderFile(path, options, fn);
100
```
101

102
[Template Rendering](./rendering.md)
103

104
### Client-Side Compilation
105

106
Browser-compatible template compilation for client-side rendering. Generates standalone JavaScript code that can run without Node.js dependencies.
107

108
```javascript { .api }
109
/**
110
 * Compile template to JavaScript source for browser use
111
 * @param str - Pug template source code
112
 * @param options - Client compilation options
113
 * @returns JavaScript source code string
114
 */
115
function compileClient(str, options);
116

117
/**
118
 * Compile template file to client-side JavaScript
119
 * @param path - Path to Pug template file
120
 * @param options - Client compilation options
121
 * @returns JavaScript source code string with caching
122
 */
123
function compileFileClient(path, options);
124

125
/**
126
 * Compile template with dependency tracking
127
 * @param str - Pug template source code
128
 * @param options - Compilation options
129
 * @returns Object with body (JavaScript code) and dependencies array
130
 */
131
function compileClientWithDependenciesTracked(str, options);
132
```
133

134
[Client-Side Compilation](./client-compilation.md)
135

136
### Configuration and Caching
137

138
Template caching, global filters, and runtime configuration for optimizing performance and extending functionality.
139

140
```javascript { .api }
141
/**
142
 * Template function cache for compiled templates
143
 */
144
const cache;
145

146
/**
147
 * Global custom filters registry
148
 */
149
const filters;
150

151
/**
152
 * Pug runtime helpers for template execution
153
 */
154
const runtime;
155

156
/**
157
 * Library identification name
158
 */
159
const name;
160
```
161

162
[Configuration and Caching](./configuration.md)
163

164
### Express.js Integration
165

166
Native Express.js view engine support for seamless web application integration.
167

168
```javascript { .api }
169
/**
170
 * Express.js view engine interface
171
 * @param path - Template file path
172
 * @param options - View options from Express
173
 * @param fn - Express callback function
174
 */
175
function __express(path, options, fn);
176
```
177

178
[Express Integration](./express-integration.md)
179

180
### Node.js require() Registration
181

182
Direct .pug file support through Node.js require() system for seamless template loading in applications.
183

184
```javascript { .api }
185
/**
186
 * Register .pug extension with Node.js require() system
187
 */
188
require('pug/register');
189
```
190

191
[Configuration and Caching](./configuration.md)
192

193
## Common Options
194

195
Most functions accept an options object with these common properties:
196

197
```javascript { .api }
198
interface PugOptions {
199
  /** Used for error reporting and resolving includes/extends */
200
  filename?: string;
201
  /** Include debugging information (default: true in development) */
202
  compileDebug?: boolean;
203
  /** Add pretty-indentation to output (default: false) */
204
  pretty?: boolean;
205
  /** Base directory for resolving includes and extends */
206
  basedir?: string;
207
  /** Set default doctype if not specified in template */
208
  doctype?: string;
209
  /** Custom filters for template processing */
210
  filters?: { [name: string]: Function };
211
  /** Options passed to filters */
212
  filterOptions?: any;
213
  /** Aliases for filter names */
214
  filterAliases?: { [alias: string]: string };
215
  /** Variables to make available globally in templates */
216
  globals?: string[];
217
  /** Use self namespace for locals (default: false) */
218
  self?: boolean;
219
  /** Enable template caching (requires filename) */
220
  cache?: boolean;
221
  /** Inline runtime functions in generated code */
222
  inlineRuntimeFunctions?: boolean;
223
  /** Array of compilation plugins */
224
  plugins?: PugPlugin[];
225
  /** Include source maps in debug builds */
226
  includeSources?: boolean;
227
  /** Name for the generated template function */
228
  templateName?: string;
229
  /** Debug compilation process */
230
  debug?: boolean;
231
}
232
```
233

234
## Types
235

236
```javascript { .api }
237
/**
238
 * Compiled template function
239
 */
240
type TemplateFunction = (locals?: any) => string;
241

242
/**
243
 * Plugin interface for extending Pug compilation
244
 */
245
interface PugPlugin {
246
  /** Hook into lexical analysis stage */
247
  lex?: Function;
248
  /** Hook into parsing stage */
249
  parse?: Function;
250
  /** Custom file resolution */
251
  resolve?: Function;
252
  /** Custom file reading */
253
  read?: Function;
254
  /** Custom code generation */
255
  generateCode?: Function;
256
  /** Pre-processing hooks */
257
  preLex?: Function;
258
  postLex?: Function;
259
  preParse?: Function;
260
  postParse?: Function;
261
  preLoad?: Function;
262
  postLoad?: Function;
263
  preFilters?: Function;
264
  postFilters?: Function;
265
  preLink?: Function;
266
  postLink?: Function;
267
  preCodeGen?: Function;
268
  postCodeGen?: Function;
269
}
270

271
/**
272
 * Compilation result with dependency tracking
273
 */
274
interface CompilationResult {
275
  /** Generated JavaScript code */
276
  body: string;
277
  /** Array of file dependencies */
278
  dependencies: string[];
279
}
280
```