eleventy-nunjucks
Skill5 starsChanged 49 days agoMITView on GitHub
Build, debug, and review Eleventy v3 sites and Nunjucks templates. Use when `package.json` includes `@11ty/eleventy` or `@awesome.me/buildawesome`; when paths include `.eleventy.js`, `eleventy.config.*`, `.njk`, `.11tydata.js`, or `.11ty.js`; when asked to \"create an 11ty page\", \"add a Nunjucks filter\", \"fix my layout chain\", \"review my .njk template\", \"set up Eleventy\", or \"migrate to Build Awesome\" (v4 prerelease); or when debugging Eleventy data cascades, shortcodes, autoescape, or `| safe` output. Standalone Nunjucks work is in scope; generic static-site, SSG, or CSP tasks need confirmed Eleventy or Nunjucks context.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-memorySkill
- code-to-figmaSkill
- discord-harvestSkill
- figma-to-codeSkill
- init-rulebookSkill
- localhost-screenshotsSkill
- skill-architectSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 2 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Before calling work complete, verify the project-specific result rather than only applying this skill's defaults:
- Very specific: line 34
Every new or changed | safe, custom autoescape extensions, inline JSON/script data path, and markdown html setting has been reviewed …
- Distinctive: line 42
Read paths from the active project config.
- Very specific: line 61
Layout chain: prefer layout: and {{ content | safe }} for site shells that require Eleventy layout frontmatter, cascade behavior, or layout …
- Very specific: line 63
Autoescape: treat every | safe as a security boundary.
- Very specific: line 65
Inline data in
<script>: use jsonScript or jsonCompact (see references/filters.md), not raw JSON.stringify or dump | safe. - Very specific: line 69
Passthrough copy: prefer explicit { "src/path": "dest/path" } maps — never copy src//* blindly.
- Very specific: line 71
CSP: prefer production HTTP headers.
- Very specific: line 75
Markdown trust: keep html: false for untrusted Markdown data.
- Very specific: line 144
Ground truth wins: when a project's checked-in .eleventy.js / eleventy.config.js disagrees with this skill, the project wins.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 October 20, 2026 via npm dist-tags and release notes): Eleventy
3.1.7(released 2026-10-15) is the stable production baseline; it aliasesnunjucksto@11ty/nunjucks@3.3.0, which keeps Mozilla Nunjucks3.2.4behavior. If the stablelatesttag is newer than3.1.7, read the intervening release notes before relying on version-specific claims. Build Awesome4.0.0-alpha.10is a prerelease available through@11ty/eleventy@canaryor@awesome.me/buildawesome@alpha. Existing Eleventy commands remain compatible, but v4 changes runtime and template behavior. Keep stable guidance as the default and loadreferences/build-awesome-v4.mdbefore any v4 install or migration.
Operating procedure
- 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. - 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, loadbuild-awesome-v4.mdand enforce its version-drift stop condition. Generic.data.*/.server.*names alone are not proof of v4: confirm package identity and resolved version first. - 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.7 + Nunjucks 3 (@11ty/nunjucks@3.3.0 under Eleventy; Mozilla nunjucks@3.2.4 standalone). 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:
- The relevant Eleventy build, dev-server smoke check, or project test command passes.
- Site shells that need layout frontmatter, cascade behavior, or layout chaining use Eleventy
layout:and render{{ content | safe }}intentionally; any Nunjucksextendsusage is reviewed as a separate inheritance path. - Every new or changed
| safe, custom autoescape extensions, inline JSON/script data path, and markdownhtmlsetting has been reviewed against the trust boundary. - The task-specific reference checklist was applied when relevant (
review-shipping.mdfor PR review,security-checklist.mdfor deploy/security, etc.). - 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.7 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.
eleventyComputed- Template frontmatter
- Template data files
- Directory data files, ascending through parent directories
- Layout frontmatter
eleventyConfig.addGlobalData- 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
safefilter only to trusted, sanitized HTML (or to the output ofjsonScript/jsonCompactinside<script>as documented inreferences/filters.md). - Stock Nunjucks 3 has no
{% autoescape %}block tag. Keep environment autoescaping enabled; review custom extensions separately. - Markdown piped through a custom
mdfilter is only as safe asmarkdown-it’shtmlflag — keephtml: falsefor 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 seven cases covering version selection, layout debugging, Markdown trust, inline-script escaping review, project conventions, configured audit paths, 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).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

