Layouts

Layouts let you reuse the same consistent page structure across multiple pages.

You can use layouts to add headers, footers, navigation, meta tags and other elements to your pages. If you find yourself repeating the same HTML in different templates, it might be a good time to move that component into a layout instead.

There are two ways to add a layout. You can either add the layout explicitly to your template data, or create a directory layout alongside a template.

Explicit layouts

Layouts are compiled in the same way as templates, with different file extensions matching different compilers. When a layout does not include a file extension, Night Owl looks for a Pug template with that name.

Markdown

For a Markdown template, declare a layout in your front‑matter.

---
layout: "_/layouts/my-layout"
---

JavaScript

For a JavaScript template, declare a layout in your data.

export default {
  layout: "_/layouts/my-layout",
}

An alternative way to control how JavaScript templates render is to add a render function.

Pug

You can use layouts in Pug templates, but they work differently to Pug’s built‑in layouts. Pug’s block syntax will only work when you also use extend.

In the template below, the my-layout-block block is unaware of blocks that occur in _/layouts/my-layout.

---
layout: "_/layouts/my-layout"
---

block my-layout-block
  h1 Title

To fix this, remove layout from the front‑matter and use extends instead.

extends _/layouts/my-layout

block my-layout-block
  h1 Title

Note that using extends requires the layout to be recompiled each time the template changes. When possible, it is best to use the first method, setting the layout in your front‑matter. These layouts are only recompiled when the layout changes, which will improve build times.

Directory layouts

When Night Owl finds a _layout.pug file, the file will be used as the default layout for all of the templates in same directory. This only happens when there isn’t any explicit layout defined in the template data.

Layout data

Layouts can also declare data using front‑matter.

---
myVariable: 42
---

extends default-layout

Layout data overrides Global data, but will be replaced by Template data.

However, you cannot use front‑matter in any files that a layout extends or includes. In the example above, using front‑matter in default-layout.pug will cause an error.

Nested layouts

When the layout data includes a layout, Night Owl will use that new layout to wrap the current one. Layouts can be nested multiple times, and each new layout can provide additional layout data.

Deeply nested layouts should be used carefully. It can be difficult to reason about the layout chain and its effects on the template content. Night Owl sets a limit on the number of nested layouts using the maxLayoutDepth option.

Only explicit layouts will be nested. Night Owl won’t automatically nest directory layouts, unless they include an explicit layout in their data.

Default layout

To set a default layout for all of your templates that generate HTML pages, add a layout to your Global data.