eleventy-playbook

name	eleventy-playbook
description	Technical constraints, gotchas, and debugging tips specific to this site's Eleventy 3.0 configuration and data cascade.

Eleventy Debugging Playbook

This skill outlines the specific quirks and patterns of this site's Eleventy configuration to accelerate debugging.

Common Gotchas

1. templateContent Lazy Evaluation in Collections

• The Problem: In eleventy.config.mjs, when mapping custom collections (like feed), creating a new object with a detached getter try { return entry.templateContent; } fails to render the HTML body in Nunjucks templates (like feed-card.njk).
• The Fix: Pass the raw Eleventy item instead (original: entry). Nunjucks handles item.original.templateContent correctly when the original object context is preserved.

2. UI Tag Badges

• The Problem: You added a new organizational tag (e.g., lexicon, til, now) and now it appears as a weird badge on every post card.
• The Fix: Internal tags used for routing and collections must be excluded from the UI. Add the tag to the filterTagList function inside eleventy.config.mjs.

3. Date Volatility

• The Problem: A page's date changes every time it is deployed or modified.
• The Fix: Never rely on file system modification times. All content must explicitly declare date (and updated, if applicable) in its YAML frontmatter.

4. Custom UI Surfaces

• The Problem: You are building a new component and trying to style it with utility classes like bg-white shadow-md p-4 rounded-lg.
• The Fix: The site uses a specific "Dense Editorial / Workbench" design language. Use the centralized tokens (e.g., .surface, .surface-compact) instead of raw utility classes to ensure dark mode and theme consistency.