Pug Layout Inheritance: extends and block

Problem: Duplicated Layout Markup

Many web projects repeat the same HTML skeleton—doctype, head, header, footer—in every template. This duplication makes global updates error-prone and bloats file size.

Thesis: Pug’s Inheritance System

Pug provides a declarative way to define a base layout once and reuse it across all views through the extends and block directives.

How extends and block Work

In a base layout file, block content acts as a placeholder. Child templates extend that layout and block content with page-specific markup. The inherited structure wraps the filled block, so only the unique content changes per view.

1. Create a layout file with a block content section.
2. Create a child view that extends the layout and defines block content.
3. Compile the child file and inspect the generated HTML to confirm the layout applies.

Example Files

layout.pug
doctype html
html
  head
    title My Site
  body
    header Nav
    block content
    footer © 2024

home.pug
extends layout.pug
block content
  h1 Welcome
  p This is the home page.

When home.pug is compiled, the output includes the doctype, html, head, header, and footer from layout.pug, with the block content replaced by the markup inside home.pug.

Using Inheritance with Express

In an Express application, Pug can be set as the view engine. A layout file renders once, and each route renders a child template that extends the layout. This reduces rendering overhead and simplifies asset management because the common HTML structure is generated a single time.

Trade-offs and Limitations

• Path validation: Using dynamic template names with extends can expose template files to injection if user input is passed directly to the path. Always validate and sanitize template references.
• Relative path resolution: File paths are relative to the rendering file. Mis-configured paths can lead to silent failures or missing content. Double-check the location of layout files relative to child views.
• Engine mixing: When combining Pug with other templating engines in the same project, ensure layout files are not accidentally overridden or duplicated.
• Inheritance depth: Deeply nested inheritance chains can increase compilation time. Keep the depth of nested layouts reasonable.

Verification Steps

1. Create a base layout file layout.pug containing a block content section and a header/footer.
2. Create a child view home.pug that extends layout.pug and defines the block content with page-specific markup.
3. Compile the child file with the pug CLI (pug home.pug -o output) and inspect the generated HTML to confirm the layout is applied.
4. Set up a minimal Express route rendering home.pug and verify the response in a browser to ensure the layout renders correctly.
5. Optionally, use the online Pug REPL to paste both files and observe the rendered output instantly.