eleventy-nunjucks

Eleventy + Nunjucks

Eleventy v3 と Nunjucks の静的サイト向け運用上のデフォルト設定です。ディレクトリ構成、設定項目、フィルター一覧、自動エスケープのルール、安定性とセキュリティの確認項目をまとめています。テンプレートの作成、ビルド設定の編集、マージやデプロイ前の静的出力のレビュー時に、このスキルを読み込んでください。

バージョンの境界（2026-10-20 に npm の dist-tag とリリースノートで再確認）： 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 のレイアウトフロントマター、カスケード動作、またはレイアウトの連結が必要なサイトのシェルでは、layout: と {{ content | safe }} を優先します。Nunjucks の {% extends %} もサポートされていますが、拡張先の親テンプレートのフロントマターは処理されません。

自動エスケープ： すべての | safe をセキュリティ境界として扱います。ユーザー、CMS、または外部の HTML を、サニタイズせずに安全と見なしてはいけません。dump は <pre> 内でのデバッグ用であり、実行可能な <script> 内では使用しません。

<script> 内のインラインデータ： 生の JSON.stringify や dump | safe ではなく、jsonScript または jsonCompact を使用します（references/filters.md を参照）。

フラットなパーマリンクと nginx の try_files $uri.html： page.url の末尾に .html が付く場合があります。ナビゲーションのアクティブ状態と正規 URL には normalize_path を使用します（references/filters.md を参照）。

パススルーコピー： 明示的な { "src/path": "dest/path" } マップを優先します。src/**/* を無条件にコピーしてはいけません。

CSP： 本番環境の HTTP ヘッダーを優先します。プロジェクトで CSP の <meta> を使用する場合は、ライブリロードを許可するため、--serve 中は省略するか調整します。frame-ancestors は HTTP ヘッダーで指定し、<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. テンプレートのフロントマター
3. テンプレートデータファイル
4. 親ディレクトリへとさかのぼるディレクトリデータファイル
5. レイアウトのフロントマター
6. eleventyConfig.addGlobalData
7. グローバルデータファイル

具体例とページネーションについては、references/data-cascade.md を参照してください。

---

Autoescape と safe フィルター

foo に、イベントハンドラー付きのタグなど、信頼できない HTML が格納されているとします。

状態	{{ foo }} の結果
autoescape: true（デフォルト）	エスケープ済み — テキストノードで安全です
autoescape: true で、値に safe フィルターを適用	生の HTML — foo が信頼できない場合は XSS の危険があります
autoescape: false	生の HTML — グローバルな XSS リスクとして扱ってください
autoescape: false で、escape フィルターを適用	再度エスケープされます

覚えておきたいルール：

• safe フィルターは、信頼できるサニタイズ済みの HTML（または 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、セクションの重複、予期しない自動エスケープ、ビルドの停止

動作評価

作成者／レビュアーのみ： このスキルを明示的に評価する場合は、評価カタログを使用してください。通常のサイト作業では使用しないでください。カタログには、バージョンの選択、レイアウトのデバッグ、Markdown の信頼性、インラインスクリプトのエスケープレビュー、プロジェクト規約、設定済みの監査パス、検索の境界を対象とした 7 つのケースが含まれており、入力例と採点基準が用意されています。実行中のエージェントには評価基準を見せず、観察結果は別途記録してください。既存のレンダリングテストはスニペットを検証しますが、これらのシナリオではエージェントがガイダンスを適切に適用するかを確認します。合成されたバージョン一覧は v4 の実行を証明するものではなく、説明文のみによるルーティングではホスト側の検出能力を測定できません。

---

関連スキル

同じモノレポ（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 を適用します）。