eleventy-nunjucks

Eleventy + Nunjucks

适用于 Eleventy v3 和 Nunjucks 静态站点的操作默认规范——目录布局、配置范围、过滤器清单、自动转义规则、稳定性与安全检查。在编写模板、编辑构建配置，或在合并或部署前审查静态输出时加载此技能。

**版本边界（于 2026 年 10 月 20 日通过 npm dist-tags 和发行说明重新核验）：**Eleventy 3.1.7（于 2026-10-15 发布）是稳定的生产基线；它将 nunjucks 指向 @11ty/[email protected]，后者保持了 Mozilla Nunjucks 3.2.4 的行为。如果稳定的 latest 标签比 3.1.7 更新，请先阅读期间的发行说明，再依赖特定版本的说明。Build Awesome 4.0.0-alpha.10 是预发布版本，可通过 @11ty/eleventy@canary 或 @awesome.me/buildawesome@alpha 获取。现有 Eleventy 命令仍兼容，但 v4 会改变运行时和模板行为。默认采用稳定版指南；在安装或迁移到任何 v4 版本前，先加载 references/build-awesome-v4.md。

---

操作流程

1. **打开 package.json、其锁文件和当前启用的 Eleventy 配置。**确认已安装的包和版本、模块类型、Node 引擎，以及 Eleventy 优先解析的配置文件名。以项目中已提交的行为为准。
2. **选择适用版本线。**默认采用稳定版 v3 指南。如果项目使用 v4 canary、Build Awesome 包，或其配置显式启用了通用 .data.* / .server.* 后缀，请加载 build-awesome-v4.md，并遵循其中的版本漂移停止条件。仅凭通用 .data.* / .server.* 名称并不能证明项目使用 v4：请先确认包身份和解析出的版本。
3. **打开下表中与任务相关的参考文档。**除非变更范围很大，否则不要加载所有参考文档。

通用核心内容以 Eleventy 3.1.7 + Nunjucks 3 为目标（Eleventy 使用 @11ty/[email protected]；独立使用时为 Mozilla [email protected]）。与版本相关的 v4 指南单独放在预发布版本参考文档中。若要核实上游变更，请优先查阅 11ty.dev、11ty/buildawesome 和当前包元数据；将带日期的说明视为需要重新核验的标记。

完成检查

在宣布工作完成前，请验证项目实际结果，而不只是套用本技能的默认规范：

1. 相关的 Eleventy 构建、开发服务器冒烟测试或项目测试命令均通过。
2. 需要布局 frontmatter、级联行为或布局链的站点外壳使用 Eleventy 的 layout:，并有意渲染 {{ content | safe }}；任何 Nunjucks extends 用法都应作为单独的继承路径审查。
3. 所有新增或变更的 | safe、自定义自动转义扩展、内联 JSON/脚本数据路径以及 Markdown 的 html 设置，都已根据信任边界进行审查。
4. 相关任务的参考清单已应用（PR 审查使用 review-shipping.md，部署/安全审查使用 security-checklist.md 等）。
5. 已检查受影响页面、布局、过滤器、短代码或数据级联所生成的渲染结果或 HTML。

---

心智模型（30 秒）

从当前项目配置中读取路径。可选的生产配置方案是一份配方，并非 Eleventy 默认设置，也不是迁移现有项目的理由。

主题	框架行为或项目选择
Eleventy	默认使用稳定版 v3.1.7；Build Awesome v4 仍为预发布版本，且受版本限制
Node	v3 的软件包最低要求为 >=18；请使用受支持的 LTS 版本（推荐 Node 24，也支持 Node 22）。v4 预发布版要求 >=22.15。
配置名称	搜索顺序：.eleventy.js、eleventy.config.js、eleventy.config.mjs、eleventy.config.cjs；采用第一个匹配项
引擎	.njk、.md、.html —— 当 markdownTemplateEngine 为 njk 时，Markdown 会经过 Nunjucks 处理
输出目录	Eleventy 默认使用 _site/；保留已配置的 dir.output。可选的生产配置方案：out/。
输入	Eleventy 默认使用项目根目录；保留已配置的 dir.input。可选的生产配置方案：src/pages/ 或 src/。
布局	从已配置的布局／包含目录中解析；通过 layout: 链接。可选的生产配置方案：src/_includes/layouts/。
分区／宏	遵循现有的包含路径。可选的生产配置方案：src/_includes/sections/… 和 src/_includes/macros/…。
数据	使用已配置的全局数据目录，以及目录／模板数据。可选的生产配置方案：src/_data/。参见 references/data-cascade.md。
CSS	由项目选择；可选配置方案使用 Tailwind v4 CLI + concurrently --kill-others-on-fail

---

不可妥协的规则

布局链： 对于需要 Eleventy 布局 Front Matter、级联行为或布局链接的网站外壳，优先使用 layout: 和 {{ content | safe }}。支持 Nunjucks {% extends %}，但不会处理被扩展的父模板中的 Front Matter。

自动转义： 将每个 | safe 都视为安全边界。未经清理，绝不要将用户、CMS 或外部 HTML 标记为安全内容。dump 用于在 <pre> 中调试，不要放在可执行的 <script> 中。

<script> 中的内联数据： 使用 jsonScript 或 jsonCompact（参见 references/filters.md），不要使用原始的 JSON.stringify 或 dump | safe。

扁平永久链接 + nginx try_files $uri.html： page.url 可能以 .html 结尾。请使用 normalize_path（参见 references/filters.md）处理导航激活状态和规范 URL。

直通复制： 优先使用显式的 { "src/path": "dest/path" } 映射 —— 绝不要盲目复制 src/**/*。

CSP： 优先使用生产环境 HTTP 标头。如果项目使用 CSP <meta>，请在 --serve 期间省略或调整它，以允许实时重新加载。通过 HTTP 标头提供 frame-ancestors，绝不要使用 <meta>。

宏与作用域： {% import %} 默认不会继承页面作用域。如果宏会读取 page.* / site.*，请使用 with context 或显式传递参数（参见 references/nunjucks-syntax.md）。

Markdown 信任： 对不受信任的 Markdown 数据，保持 html: false。Nunjucks 模板源必须可信：Markdown 预处理会在 Markdown 渲染之前执行，因此 html: false 无法隔离 .md 模板。通过 md 过滤器将不受信任的文本作为数据渲染；绝不要将其编译为 Nunjucks 源码。

添加新过滤器前： 检查项目配置和 Nunjucks 内置过滤器，确认是否已有用途相同的过滤器 —— 常见的 11ty 项目会在不同文件中重复定义 where，且强制类型转换行为不兼容。

---

数据级联（优先级顺序）

优先级最高者生效。当变量缺失或错误时，在考虑 page、collections 或 eleventy 等 Eleventy 提供的值之前，先按此官方顺序追查。

1. eleventyComputed
2. 模板 Front Matter
3. 模板数据文件
4. 目录数据文件，逐级向上遍历父目录
5. 布局 Front Matter
6. eleventyConfig.addGlobalData
7. 全局数据文件

示例和分页：references/data-cascade.md。

---

自动转义与 safe 过滤器

假设 foo 包含不可信的 HTML，例如带有事件处理程序的标签。

状态	{{ foo }} 的结果
autoescape: true（默认）	已转义——对文本节点安全
autoescape: true，且值经 safe 过滤器处理	原始 HTML——如果 foo 不可信，则存在 XSS 风险
autoescape: false	原始 HTML——应视为全局 XSS 风险
autoescape: false，且应用了 escape 过滤器	再次转义

经验法则：

• 仅对可信且经过净化的 HTML 使用 safe 过滤器（或者按照 references/filters.md 中的说明，在 <script> 内对 jsonScript / jsonCompact 的输出使用该过滤器）。
• 原版 Nunjucks 3 没有 {% autoescape %} 块标签。请保持环境自动转义功能启用；自定义扩展需单独审查。
• 经自定义 md 过滤器处理的 Markdown，其安全性取决于 markdown-it 的 html 标志——对于任何并非完全可信的内容，请保持 html: false。

Nunjucks 标签和宏的完整规则：references/nunjucks-syntax.md。

---

参考文件

文件	何时加载
references/eleventy-config-api.md	v2→v3 迁移、配置骨架、addFilter / 事件 / 集合 / 服务选项
references/build-awesome-v4.md	Build Awesome v4 预发布版本检测、迁移门槛、Node/Nunjucks/数据变更
references/conventions.md	目录布局、dir 矩阵、命名、脚本结构、何时偏离约定
references/data-cascade.md	合并顺序、eleventyComputed、分页、示例追踪
references/filters.md	规范过滤器来源、normalize_path、jsonScript、异步过滤器
references/nunjucks-syntax.md	标签、宏、with context、内置过滤器、extends 与 11ty 布局的区别
references/build-pipeline.md	Tailwind v4 + concurrently、lint/format、清理目标
references/production-patterns.md	CSP、可选的软导航契约、nginx、构建后钩子、OG/JSON-LD 模式
references/review-shipping.md	PR grep、稳定性检查清单、反模式、页面范例
references/security-checklist.md	部署前 XSS、标头、直通配置、机密审计
references/troubleshooting.md	--serve 时出现 404、重复区块、自动转义意外行为、构建挂起

行为评估

**仅供作者/审阅者使用：**仅在明确评估此技能时使用评估目录；常规网站工作时请跳过。它包含 7 个案例，涵盖版本选择、布局调试、Markdown 信任、内联脚本转义审查、项目约定、已配置的审计路径和检索边界，并提供固定输入和评分标准。请对执行任务的 Agent 隐藏断言，并单独记录观察结果。现有渲染测试会验证代码片段；这些场景则用于检查 Agent 是否恰当地应用指南。合成版本清单不能证明 v4 已实际运行，仅基于描述进行路由也无法衡量宿主发现能力。

---

相关技能

同一 monorepo（skills4sh）： agent-memory（跨会话上下文）、localhost-screenshots（静态网站的视觉回归）。

以实际情况为准： 当项目已提交的 .eleventy.js / eleventy.config.js 与此技能不一致时，以项目为准。应用这里的约定前，务必先阅读实际配置和 package.json 脚本。

---

最简布局提醒

示例：子页面

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

示例：layouts/page.njk

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

每个父级都会通过 content 渲染子级编译后的正文，然后在子级输出 HTML 时通过 safe 处理（用于插入 HTML 的 11ty 布局总会对 content 使用 safe）。