Introduction to Pug

History: From Jade to Pug

Pug was originally called Jade, created by TJ Holowaychuk in 2010. Renamed to Pug in 2016 due to a trademark conflict. The philosophy: write less markup, produce clean HTML through indentation-based syntax — no closing tags, no angle brackets.

Tags & Nesting

//- Pug
div
  h1 Welcome
  p This is a paragraph.
  ul
    li Item one
    li Item two

<!-- HTML Output -->
<div>
  <h1>Welcome</h1>
  <p>This is a paragraph.</p>
  <ul>
    <li>Item one</li>
    <li>Item two</li>
  </ul>
</div>

CSS-Selector Shorthand

//- Classes with .
div.container
  p.lead.text-center Hello

//- IDs with #
div#app
  h1#title My App

//- Combined
div#main.wrapper.dark

//- Implicit div (omit tag name)
.container
  #sidebar
    p Content

<!-- HTML Output -->
<div class="container">
  <div id="sidebar">
    <p>Content</p>
  </div>
</div>

Buffered vs Unbuffered Code

//- Buffered (outputs escaped)
p= user.name

//- Unbuffered (no output, runs JS)
- var x = 10
- var items = ['a', 'b', 'c']

//- Unescaped buffered
p!= richContent

if / else if / else

if user.role === 'admin'
  .badge.admin Admin
else if user.role === 'editor'
  .badge.editor Editor
else
  .badge.member Member

<!-- No braces, no parentheses -->
<!-- Indentation defines scope -->

each (Most Common)

ul
  each user in users
    li #{user.name} — #{user.email}

//- With index
ul
  each item, i in items
    li #{i + 1}. #{item.name}

Nested Iteration

each category in categories
  h2= category.name
  ul
    each item in category.items
      li= item.title

Defining & Calling

//- Define a mixin
mixin card(title, text)
  .card
    h3= title
    p= text

//- Call the mixin
+card('Hello', 'World')
+card('Pug', 'Template engine')

<!-- HTML Output -->
<div class="card">
  <h3>Hello</h3>
  <p>World</p>
</div>
<div class="card">
  <h3>Pug</h3>
  <p>Template engine</p>
</div>

extends & block

//- views/layout.pug (base template)
doctype html
html(lang="en")
  head
    meta(charset="UTF-8")
    title #{title} | My App
    block styles
      link(rel="stylesheet", href="/css/main.css")
  body
    include partials/nav
    main.container
      block content
    include partials/footer
    block scripts

Basic Include Syntax

//- Include a Pug file (no extension needed)
include partials/nav

//- Include with a relative path
include ./components/sidebar

//- Include a plain-text file
include:css styles/inline.css
include plaintext.txt

Pug includes are resolved relative to the current file. The included file is compiled as Pug by default.

What Are Filters?

Filters let you embed other languages inside Pug templates. The content is processed by an external module at compile time and the result is inserted into the HTML output.

//- General syntax
:filterName
  Content processed by filterName

Basic Setup

const express = require('express');
const path = require('path');
const app = express();

// Set Pug as the view engine
app.set('view engine', 'pug');

// Set the views directory
app.set('views',
  path.join(__dirname, 'views'));

// Render a template
app.get('/', (req, res) => {
  res.render('index', {
    title: 'Home'
  });
});

Express calls pug.__express under the hood — no extra middleware needed.

res.render() Data Object

// Route handler
app.get('/dashboard', async (req, res) => {
  const user = await User.findById(req.user.id);
  const stats = await getStats(user.id);

  res.render('dashboard', {
    title: 'Dashboard',
    user,
    stats,
    isAdmin: user.role === 'admin',
    formatDate: (d) =>
      d.toLocaleDateString('en-GB')
  });
});

Rule of Thumb

How Pug Compiles Templates

Pug uses a 3-stage pipeline: lexer (tokenise), parser (build AST), code generator (emit JS function). The compiled function is cached and reused.

Directory Layout

my-app/
├── app.js
├── package.json
├── .env
├── config/
│   └── db.js
├── routes/
│   ├── index.js
│   ├── auth.js
│   └── products.js
├── controllers/
│   ├── authController.js
│   └── productController.js
├── models/
│   ├── User.js
│   └── Product.js
├── middleware/
│   ├── auth.js
│   └── validate.js
├── views/
│   ├── layout.pug
│   ├── mixins/
│   │   ├── card.pug
│   │   └── form-field.pug
│   ├── partials/
│   │   ├── nav.pug
│   │   ├── flash.pug
│   │   └── footer.pug
│   ├── pages/
│   │   ├── home.pug
│   │   ├── about.pug
│   │   └── contact.pug
│   ├── auth/
│   │   ├── login.pug
│   │   └── register.pug
│   ├── products/
│   │   ├── index.pug
│   │   ├── show.pug
│   │   └── edit.pug
│   └── error.pug
└── public/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/