eleventy-nunjucks

Eleventy + Nunjucks

Operational defaults for Eleventy v3 and Nunjucks static sites — directory layout, configuration surface, filter inventory, autoescape rules, stability and security checks. Load this skill when authoring templates, editing build config, or reviewing static output before merge or deploy.

Version boundary (rechecked September 13, 2026): Eleventy 3.1.6 is the stable production baseline. Build Awesome 4.0.0-alpha.10 is a prerelease available through @11ty/eleventy@canary or @awesome.me/buildawesome@alpha. Existing Eleventy commands remain compatible, but v4 changes runtime and template behavior. Keep stable guidance as the default and load references/build-awesome-v4.md before any v4 install or migration.

When this skill applies

Use explicit Eleventy/Build Awesome or Nunjucks context. Generic static-site/security topics and .data.*/.server.* filenames alone do not select this skill over another framework. Standalone Nunjucks work is in scope; apply Eleventy-specific steps only when that project uses Eleventy. Relevant cues include:

• Paths mentioning .eleventy.js, eleventy.config.{js,mjs,cjs}, .njk, .11tydata.js, .data.js, .11ty.js, .server.js, src/_includes/, or src/_data/
• package.json lists @11ty/eleventy or @awesome.me/buildawesome
• Topics: 11ty, Eleventy, Nunjucks, SSG, JAMstack, static site, layout chain, permalink, collection, shortcode, filter, dev server, CSP, JSON-LD in templates

---

Operating procedure

1. Open package.json, its lockfile, and the active Eleventy config. Identify the installed package/version, module type, Node engine, and the first config filename Eleventy resolves. Checked-in project behavior always wins.
2. Choose the track. Use the stable v3 guidance by default. If the project uses a v4 canary, the Build Awesome package, or its config explicitly enables the generic .data.* / .server.* suffixes, load build-awesome-v4.md and enforce its version-drift stop condition. Generic .data.* / .server.* names alone are not proof of v4: confirm package identity and resolved version first.
3. Open the task-specific reference from the table below. Avoid loading every reference unless the change is large.

The portable core targets Eleventy 3.1.6 + Mozilla Nunjucks 3.2.4. Version-sensitive v4 guidance is isolated in the prerelease reference. For upstream drift, prefer 11ty.dev, 11ty/buildawesome, and the active package metadata; treat dated claims as revalidation markers.

Completion gate

Before calling work complete, verify the project-specific result rather than only applying this skill's defaults:

1. The relevant Eleventy build, dev-server smoke check, or project test command passes.
2. Site shells that need layout frontmatter, cascade behavior, or layout chaining use Eleventy layout: and render {{ content | safe }} intentionally; any Nunjucks extends usage is reviewed as a separate inheritance path.
3. Every new or changed | safe, custom autoescape extensions, inline JSON/script data path, and markdown html setting has been reviewed against the trust boundary.
4. The task-specific reference checklist was applied when relevant (review-shipping.md for PR review, security-checklist.md for deploy/security, etc.).
5. Rendered output or generated HTML was inspected for the touched page, layout, filter, shortcode, or data cascade.

---

Mental model (30 seconds)

Read paths from the active project config. The optional production profile is a recipe, not Eleventy defaults or a reason to migrate an existing project.

Topic	Framework behavior or project choice
Eleventy	Stable v3.1.6 by default; Build Awesome v4 remains prerelease and version-gated
Node	v3 package floor >=18; use a supported LTS (Node 24 preferred, Node 22 supported). v4 prerelease requires >=22.15.
Config name	Search order: .eleventy.js, eleventy.config.js, eleventy.config.mjs, eleventy.config.cjs; the first match wins
Engines	.njk, .md, .html — markdown runs through Nunjucks when markdownTemplateEngine is njk
Output dir	Eleventy default _site/; preserve configured dir.output. Optional production profile: out/.
Input	Eleventy default project root; preserve configured dir.input. Optional production profile: src/pages/ or src/.
Layouts	Resolve from configured layout/include directories; chain via layout:. Optional production profile: src/_includes/layouts/.
Sections / macros	Follow existing include paths. Optional production profile: src/_includes/sections/… and src/_includes/macros/….
Data	Use configured global-data directory plus directory/template data. Optional production profile: src/_data/. See references/data-cascade.md.
CSS	Project-selected; the optional profile uses Tailwind v4 CLI + concurrently --kill-others-on-fail

---

Non-negotiable rules

Layout chain: prefer layout: and {{ content | safe }} for site shells that require Eleventy layout frontmatter, cascade behavior, or layout chaining. Nunjucks {% extends %} is supported, but frontmatter in the extended parent template is not processed.

Autoescape: treat every | safe as a security boundary. Never mark user, CMS, or external HTML safe without sanitization. dump is for debug in <pre>, not inside executable <script>.

Inline data in <script>: use jsonScript or jsonCompact (see references/filters.md), not raw JSON.stringify or dump | safe.

Flat permalinks + nginx try_files $uri.html: page.url may end in .html. Ship normalize_path (see references/filters.md) for nav active state and canonical URLs.

Passthrough copy: prefer explicit { "src/path": "dest/path" } maps — never copy src/**/* blindly.

CSP: prefer production HTTP headers. If the project uses a CSP <meta>, omit or adapt it during --serve so live reload is allowed. Deliver frame-ancestors via HTTP headers, never <meta>.

Macros and scope: {% import %} does not inherit page scope by default. If macros read page.* / site.*, use with context or pass arguments explicitly (see references/nunjucks-syntax.md).

Markdown trust: keep html: false for untrusted Markdown data. Nunjucks template source must be trusted: Markdown preprocessing executes before Markdown rendering, so html: false does not sandbox .md templates. Render untrusted text as data through the md filter; never compile it as Nunjucks source.

Before adding a new filter: inspect the project config and Nunjucks built-ins for an existing filter with the same role — common 11ty projects duplicate where with incompatible coercion across files.

---

Data cascade (priority order)

Highest priority wins. When a variable is missing or wrong, trace this official order before considering Eleventy-supplied values such as page, collections, or eleventy.

1. eleventyComputed
2. Template frontmatter
3. Template data files
4. Directory data files, ascending through parent directories
5. Layout frontmatter
6. eleventyConfig.addGlobalData
7. Global data files

Worked examples and pagination: references/data-cascade.md.

---

Autoescape and the safe filter

Assume foo holds untrusted HTML such as a tag with an event handler.

State	Result of {{ foo }}
autoescape: true (default)	Escaped — safe for text nodes
autoescape: true and value piped through the safe filter	Raw HTML — XSS if foo is untrusted
autoescape: false	Raw HTML — treat like global XSS risk
autoescape: false and escape filter applied	Escaped again

Rules of thumb:

• Apply the safe filter only to trusted, sanitized HTML (or to the output of jsonScript / jsonCompact inside <script> as documented in references/filters.md).
• Stock Nunjucks 3 has no {% autoescape %} block tag. Keep environment autoescaping enabled; review custom extensions separately.
• Markdown piped through a custom md filter is only as safe as markdown-it’s html flag — keep html: false for anything not fully trusted.

Full Nunjucks tag and macro rules: references/nunjucks-syntax.md.

---

Reference files

File	Load when
references/eleventy-config-api.md	v2→v3 migration, config skeletons, addFilter / events / collections / server options
references/build-awesome-v4.md	Build Awesome v4 prerelease detection, migration gates, Node/Nunjucks/data changes
references/conventions.md	Directory layout, dir matrix, naming, scripts shape, when to deviate
references/data-cascade.md	Merge order, eleventyComputed, pagination, worked traces
references/filters.md	Canonical filter source, normalize_path, jsonScript, async filters
references/nunjucks-syntax.md	Tags, macros, with context, built-in filters, extends vs 11ty layouts
references/build-pipeline.md	Tailwind v4 + concurrently, lint/format, clean targets
references/production-patterns.md	CSP, optional soft-navigation contract, nginx, after-build hooks, OG/JSON-LD patterns
references/review-shipping.md	PR greps, stability checklist, anti-patterns, page recipes
references/security-checklist.md	Pre-deploy XSS, headers, passthrough, secrets audit
references/troubleshooting.md	404 on --serve, double sections, autoescape surprises, hung builds

Behavioral evaluations

Authors/reviewers only: use the evaluation catalog when explicitly evaluating this skill; skip it during normal site work. It contains five cases covering version selection, layout debugging, Markdown trust, project conventions and retrieval boundaries, with fixture inputs and grading criteria. Keep assertions hidden from the acting agent and record observed results separately. Existing render tests verify snippets; these scenarios check whether an agent applies the guidance appropriately. Synthetic version inventories do not certify v4 execution, and description-only routing does not measure host discovery.

---

Related skills

Same monorepo (skills4sh): agent-memory (cross-session context), localhost-screenshots (visual regression for static sites).

Ground truth wins: when a project's checked-in .eleventy.js / eleventy.config.js disagrees with this skill, the project wins. Always read the actual config and package.json scripts before applying conventions from here.

---

Minimal layout reminder

Example: Child page

---
layout: layouts/page.njk
title: Example
---
<section>Page body</section>

Example: layouts/page.njk

---
layout: layouts/base.njk
---
<main>{{ content | safe }}</main>

Each parent renders the child’s compiled body through content, then pipes through safe where the child emits HTML (11ty layouts that slot HTML always use safe on content).