🔹 Layouts
Supports optional layouts (layout.pug) with automatic injection of default content and live reload. The behavior adapts based on what the user layout already contains.
1️⃣ Default Layout Injection
Given a layout like:
1doctype html2html3 head4 title My App5 body6 h1 Header from layout
The engine automatically injects:
- Live reload script (always)
- Default content block if
.page!= pageis missing - Default scripts block if
.scripts!= scriptsis missing
Rendered final Pug:
1doctype html2html3 head4 title My App5 body6 h1 Header from layout8 // ✅ Injected automatically:9 script.10 const es = new EventSource('/__reload');11 es.onmessage = (e) => {12 if (e.data === 'reload') location.reload();13 };15 if page16 .page!= page18 if scripts19 .scripts!= scripts
User-defined blocks are respected — duplicates are never injected.
2️⃣ Per-View Layout Toggle
You can disable the layout per view if needed:
| View Type | How to disable layout |
|---|---|
.pug |
Add //- nolayout at the top |
.md |
Add nolayout: true in frontmatter |
.js |
Return { nolayout: true } from the async view function |
3️⃣ Injection Flow
1 ┌─────────────────────┐2 │ Load user layout.pug │3 └─────────┬───────────┘4 │5 ▼6 ┌───────────────────┐7 │ Strip comments │8 └─────────┬─────────┘9 │10 ▼11 ┌─────────────────────────────┐12 │ Build injection string │13 │ (force reload + default │14 │ content/scripts if missing) │15 └─────────┬───────────┬───────┘16 │ │17 │ ▼18 │ ┌───────────────┐19 │ │ Inject into │20 │ │ <body> tag │21 │ │ maintain │22 │ │ indentation │23 │ └─────┬─────────┘24 ▼ │25 ┌─────────────────────────────┐26 │ Compile final Pug │27 │ Render with locals │28 └─────────────────────────────┘
4️⃣ Fallback
If layout.pug does not exist:
- A default layout with all blocks and live reload is used.
- Ensures the page always renders without breaking.
5️⃣ Example Usage in a Pug Page
views/pages/index.pug:
1h1 Welcome2p Current time: {{ new Date().toLocaleTimeString() }}
Behavior:
-
If
layout.pugexists:h1 Welcomeremains intact.page!= pageis injected if missing- Live reload script is added automatically
-
If
layout.pugis missing:- Page is rendered with the default layout
.page!= pageand live reload script are included automatically
6️⃣ Automatic Injection Overview
| Injection Type | When It Happens | Notes |
|---|---|---|
| Live reload script | Always | Injected in every page rendered |
.page!= page block |
Only if missing in user layout.pug |
Ensures content is displayed without duplication |
.scripts!= scripts block |
Only if missing in user layout.pug |
Scripts section is added if not already present |
| User-defined blocks | Never overwritten | Preserves whatever user has already defined |
✅ This table helps you quickly see what the engine automatically injects versus what it preserves.