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 (verified August 6, 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

Trigger on any of:

• 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 the generic .data.* / .server.* suffixes, load build-awesome-v4.md and enforce its version-drift stop condition.
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, {% autoescape false %}, 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)

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-it html: keep html: false unless every markdown author is trusted; changing to true widens XSS risk.

Before adding a new filter: grep the project config 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.

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).
• Avoid {% autoescape false %} except in tightly reviewed fragments; prefer narrowing with per-value filters.
• 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

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

{# Child page #}
---
layout: layouts/page.njk
title: Example
---
<section>Page body</section>

{# 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).