Template Inheritance

Pug supports template inheritance. Template inheritance works via the block and extends keywords.

In a template, a block is simply a “block” of Pug that a child template may replace. This process is recursive.

Pug blocks can provide default content, if appropriate. Providing default content is purely optional, though. The example below defines block scripts, block content, and block foot.

  1. //- layout.pug
  2. html
  3.   head
  4.     title My Site - #{title}
  5.     block scripts
  6.       script(src='/jquery.js')
  7.   body
  8.     block content
  9.     block foot
  10.       #footer
  11.         p some footer content

To extend this layout, create a new file and use the extends directive with a path to the parent template. (If no file extension is given, .pug is automatically appended to the file name.) Then, define one or more blocks to override the parent block content.

Below, notice that the foot block is not redefined, so it will use the parent’s default and output “some footer content”.

  1. //- page-a.pug
  2. extends layout.pug
  4. block scripts
  5.   script(src='/jquery.js')
  6.   script(src='/pets.js')
  8. block content
  9.   h1= title
  10.   - var pets = ['cat', 'dog']
  11.   each petName in pets
  12.     include pet.pug
  1. //- pet.pug
  2. p= petName

It’s also possible to override a block to provide additional blocks, as shown in the following example. As it shows, content now exposes a sidebar and primary block for overriding. (Alternatively, the child template could override content altogether.)

  1. //- sub-layout.pug
  2. extends layout.pug
  4. block content
  5.   .sidebar
  6.     block sidebar
  7.       p nothing
  8.   .primary
  9.     block primary
  10.       p nothing
  1. //- page-b.pug
  2. extends sub-layout.pug
  4. block content
  5.   .sidebar
  6.     block sidebar
  7.       p nothing
  8.   .primary
  9.     block primary
  10.       p nothing

Block append / prepend

Pug allows you to replace (default), prepend, or append blocks.

Suppose you have default scripts in a head block that you wish to use on every page. You might do this:

  1. //- layout.pug
  2. html
  3.   head
  4.     block head
  5.       script(src='/vendor/jquery.js')
  6.       script(src='/vendor/caustic.js')
  7.   body
  8.     block content

Now, consider a page of your JavaScript game. You want some game related scripts as well as these defaults. You can simply append the block:

  1. //- page.pug
  2. extends layout.pug
  4. block append head
  5.   script(src='/vendor/three.js')
  6.   script(src='/game.js')

When using block append or block prepend, the word “block” is optional:

  1. //- page.pug
  2. extends layout
  4. append head
  5.   script(src='/vendor/three.js')
  6.   script(src='/game.js')

Common mistakes

Pug’s template inheritance is a powerful feature that allows you to split complex page template structures into smaller, simpler files. However, if you chain many, many templates together, you can make things a lot more complicated for yourself.

Note that only named blocks and mixin definitions can appear at the top (unindented) level of a child template. This is important! Parent templates define a page’s overall structure, and child templates can only append, prepend, or replace specific blocks of markup and logic. If a child template tried to add content outside of a block, Pug would have no way of knowing where to put it in the final page.

This includes unbuffered code, which can also contain markup. If you need to define variables for use in a child template, you can do so a few different ways:

  • Add the variables to the Pug options object, or define them in unbuffered code in a parent template. The child template will inherit these variables.
  • Define the variables in a block in the child template. Extending templates must have at least one block, or it would be empty — just define your variables there.

For the same reason, Pug’s buffered comments cannot appear at the top level of an extending template: they produce HTML comments which would have nowhere to go in the resulting HTML. (Unbuffered Pug comments, however, can still go anywhere.)