Diagnosing Missing Layouts in Pug Extend/Block Inheritance

Recognizable condition

The rendered page shows only the child template’s content, with no surrounding HTML layout, indicating that the `extend` directive was not applied.

Cause & diagnostic table

Possible cause	What to look for
Missing or malformed `extends` line	The child file does not start with `extends` or contains extra characters.
Wrong path in `extends`	The referenced layout file does not exist at the given relative path.
Syntax error in the parent layout	Stray characters, invalid indentation, or missing `block` definitions cause parsing to fail.

Ordered checks

1. Verify the `extends` line uses exact syntax `extends layout_name` (no quotes, no extra spaces).
2. Confirm the referenced layout file exists and is readable in the `views` folder (or whichever directory is set as `views`).
3. Ensure the layout defines a `block` matching the child’s block name (case‑sensitive).
4. Run Pug with the `-P` (pretty) flag to expose any parsing errors:

   pug -P views/child.pug

Fixes tied to findings

• If the `extends` line is missing or malformed, edit the child file to read exactly `extends layout` where `layout` is the base filename without extension.
• If the path is wrong, correct the relative path (e.g., `extends ./layout` or `extends ../layouts/main`) and verify the file exists.
• If the layout lacks a matching `block`, add `block content` (or the name used in the child) inside the layout.
• If there are syntax errors (stray characters, mixed tabs/spaces), fix them; ensure consistent indentation (spaces only, two spaces per level is common).
• After editing, re‑run the build or restart the dev server; the page should now show the inherited layout.

Example scenario

Assume a project with the following structure:

project/
├─ views/
│   ├─ layout.pug
│   └─ child.pug
└─ app.js

layout.pug:

doctype html
html
  head
    title My Site
  body
    block content

child.pug (faulty):

extends ./layout
  h1 Welcome

The `extends` line is correct, but the indentation of the block content is wrong (two spaces instead of four). Running pug -P views/child.pug yields an error about unexpected text. Fixing the indentation to match the layout’s block resolves the issue.

Verification steps

• Compile the child template without watching:

  pug -c views/child.pug

  (needs read access to the views folder). Successful exit code 0 indicates the `extends` directive was recognized.
• Inspect the generated HTML file (by default views/child.html) for a single opening <html> tag; presence of both <html> and </html> shows the layout was included.
• Check version control history or file timestamps to confirm the layout file existed when the issue occurred.

Escalation criteria

• If the checks above pass but the layout still does not appear, verify you are using Pug version 2.0 or newer (run pug -v). Versions <2.0 lack `extends` support.
• Investigate custom middleware that rewrites file paths (e.g., Express static middleware) which may cause the relative `extends` path to resolve incorrectly.
• Look for mixed tab/space indentation; enable editor visibility of whitespace to spot inconsistencies.
• When none of the above apply, consider opening an issue in the Pug repository with a minimal reproducible example.

Limitations

This guide assumes a standard Pug setup where templates are loaded from a filesystem directory. It does not cover inline templates or precompiled JavaScript functions. The verification steps rely on the CLI being available; programmatic usage may require checking the returned AST or rendered string for the layout markup.