Template inheritance vs. mixins for shared layout fragments in Pug

Direct answer

For nested blocks, template inheritance gives more predictable output than mixins.

Confirmed facts

• In Pug, extends and block resolve block slots at compile time; the generated HTML matches the source layout unless a child overrides a block.
• Mixins are defined with mixin name(args) and are invoked as JavaScript functions at render time; their output depends on the evaluated arguments.
• Under browser‑side runtime compilation (pug runtime), both approaches are rendered by the same compiled template function; inheritance blocks become internal slots, mixins become inner functions, so performance differences are minimal.

Likely explanation

Because inheritance fixes each block’s injection point by name, a child template cannot accidentally place markup in the wrong slot, even when blocks are nested. Mixins, however, accept arbitrary JavaScript expressions; if those expressions contain unsanitized data or vary between calls, the rendered fragment can change, making the output less predictable.

Steps to verify for your project

1. Create a base layout (layout.pug) with block header and block content.
2. Extend it in a child page that defines nested blocks (e.g., block header that itself contains block nav).
3. Compile with pug-cli or pug.render and inspect the HTML; the block content should appear exactly where defined.
4. Define a mixin mixin header(title) that returns the same markup, call it from multiple pages with different data, render both server‑side (Express) and client‑side (pug runtime), and compare the output.
5. If the HTML differs only in the expected data values, the mixin works; any extra variation indicates unpredictability.

Maintenance implications for a large codebase

• Inheritance encourages a single source of truth for the overall layout hierarchy; changing a block in the base file propagates everywhere, but deep inheritance chains (>3 levels) can become brittle and hard to trace.
• Mixins favor composition and localized overrides, which can simplify reuse, but layout logic may be scattered across many files, making it harder to see the full page structure at a glance.
• When dynamic data must be passed to a fragment (e.g., a page‑specific title), mixins are the natural choice; otherwise, inheritance provides clearer, more predictable block injection.

Missing diagnostic detail

Do you need to pass dynamic data (such as titles, URLs, or user‑generated content) to the shared fragment? If yes, a mixin may be required despite its lower predictability; if the fragment is purely static markup, inheritance is the safer bet.