Template Compilation and Processing Pipeline

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json) - [src/index.njk](file://src/index.njk) - [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk) - [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk) - [src/_data/site.json](file://src/_data/site.json) - [src/_data/homepage.json](file://src/_data/homepage.json) - [src/_data/capabilities.json](file://src/_data/capabilities.json) - [src/_data/testimonials.json](file://src/_data/testimonials.json) - [src/_data/polling.js](file://src/_data/polling.js) - [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json) - [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document explains how Eleventy compiles and processes templates in this project, focusing on Nunjucks-based pages and their integration with Eleventy’s data cascade. It covers the compilation order, transforms, filters, shortcodes, collections, and how global, per-collection, and page-specific data combine to produce final HTML. It also includes troubleshooting and performance guidance tailored to this codebase.

Project Structure

The project organizes templates, includes, data, and content into a conventional Eleventy layout. Templates are primarily Nunjucks (.njk) with Markdown (.md) content. Global data lives under src/_data, reusable components live under src/_includes, and content pages live under src/content. Eleventy configuration is centralized in .eleventy.js.

graph TB
A[".eleventy.js<br/>Configuration, shortcodes, filters, collections, transforms"] --> B["src/index.njk<br/>Main page using layout and macros"]
B --> C["src/_includes/layouts/base.njk<br/>Global layout and globals"]
B --> D["src/_includes/macros/service-capability-card.njk<br/>Reusable macro"]
A --> E["src/_data/site.json<br/>Site metadata"]
A --> F["src/_data/homepage.json<br/>Homepage content"]
A --> G["src/_data/capabilities.json<br/>Capabilities dataset"]
A --> H["src/_data/testimonials.json<br/>Testimonials dataset"]
A --> I["src/_data/polling.js<br/>Async data"]
A --> J["src/content/news/news.11tydata.json<br/>Per-content data override"]
A --> K["src/content/cases/cases.11tydata.json<br/>Per-content data override"]

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)
  • [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json)
  • [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json)

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [package.json](file://package.json)

Core Components

  • Configuration and Engines
    • Template engines: Nunjucks for HTML and Markdown.
    • Directory mapping: input, output, includes, data, layouts.
    • Passthrough copy for static assets and redirects.
    • Watch targets for assets and data.
  • Shortcodes
    • Year and formatted date helpers exposed to templates.
  • Filters
    • Array manipulation, date formatting, slug generation, truncation, newline-to-br conversion, first paragraph extraction, JSON dump, logging, splitting, reading time estimation, sorting, filtering, and uniqueness.
  • Collections
    • News, cases, newsletters, team members, featured news, services, knowledge.
  • Transforms
    • Obsidian-style wiki links and callouts.
    • HTML minification in production.

Section sources

  • [.eleventy.js](file://.eleventy.js)

Architecture Overview

The build pipeline proceeds as follows:

  1. Eleventy scans the configured input directory and recognizes template formats (Nunjucks, Markdown, HTML).
  2. For each template, Eleventy loads global data, per-collection data, and per-page data, merging them according to the data cascade.
  3. Nunjucks renders the template with the merged data.
  4. Optional transforms modify the output (e.g., Obsidian syntax, HTML minification).
  5. Final HTML is written to the output directory.
sequenceDiagram
participant CLI as "Eleventy CLI"
participant Cfg as ".eleventy.js"
participant Tpl as "src/index.njk"
participant Lay as "src/_includes/layouts/base.njk"
participant Mac as "src/_includes/macros/service-capability-card.njk"
participant Dat as "src/_data/*"
participant Coll as "Collections"
participant Tr as "Transforms"
participant Out as "_site"
CLI->>Cfg : Load configuration
CLI->>Tpl : Parse front matter and template
Tpl->>Dat : Resolve global data (site, homepage, datasets)
Tpl->>Coll : Resolve collections (news, teamMembers)
Tpl->>Mac : Import and render macros
Tpl->>Lay : Apply layout and pass merged data
Lay-->>CLI : Rendered HTML
CLI->>Tr : Apply transforms (wiki/callouts, minify)
Tr-->>Out : Write final HTML

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)

Detailed Component Analysis

Template Compilation and Rendering

  • Page: src/index.njk
    • Uses a layout and imports multiple macros.
    • References global data (site, homepage) and datasets (capabilities, testimonials).
    • Iterates over collections (news, teamMembers) to render dynamic content.
  • Layout: src/_includes/layouts/base.njk
    • Provides global head metadata, navigation, footer, and scripts.
    • Uses global site data and page context (title, description, url).
  • Macros: src/_includes/macros/service-capability-card.njk
    • Encapsulates a reusable card component for rendering service entries.
flowchart TD
Start(["Render src/index.njk"]) --> LoadFM["Load front matter and layout"]
LoadFM --> MergeData["Merge global data:<br/>site.json, homepage.json,<br/>capabilities.json, testimonials.json,<br/>polling.js"]
MergeData --> ResolveCollections["Resolve collections:<br/>news, teamMembers"]
ResolveCollections --> ImportMacros["Import macros and render cards"]
ImportMacros --> ApplyLayout["Apply base layout and pass merged data"]
ApplyLayout --> RenderHTML["Generate HTML"]
RenderHTML --> End(["Write to output"])

Diagram sources

  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)

Section sources

  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)

Data Cascade and Merging

  • Global data (src/_data): site.json, homepage.json, capabilities.json, testimonials.json, polling.js.
  • Per-content data overrides: src/content/news/news.11tydata.json disables permalinks for news content; src/content/cases/cases.11tydata.json similarly disables permalinks for cases.
  • Collections: news, teamMembers, services, etc., are defined in configuration and accessed via collections in templates.
graph LR
GD["Global Data (_data/*.json, *.js)"] --> MD["Merged Data"]
CD["Content Data (*.11tydata.*)"] --> MD
PD["Page Front Matter"] --> MD
COL["Collections"] --> MD
MD --> RND["Rendered Template"]

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)
  • [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json)
  • [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json)

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)
  • [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json)
  • [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json)

Filters, Shortcodes, and Transforms

  • Shortcodes: year, currentDate.
  • Filters: limit, skip, dateFormat/date, slug, truncate, nl2br, firstParagraph, dump, log, split, readingTime, sortBy, where, unique.
  • Transforms: obsidianSyntax (wiki links and callouts), htmlmin (in production).
flowchart TD
Tpl["Template"] --> Filt["Apply Filters"]
Tpl --> Scm["Insert Shortcodes"]
Filt --> Out["Intermediate HTML"]
Scm --> Out
Out --> Trns["Apply Transforms"]
Trns --> Final["Final HTML"]

Diagram sources

  • [.eleventy.js](file://.eleventy.js)

Section sources

  • [.eleventy.js](file://.eleventy.js)

Collections and Dynamic Content

  • Collections are defined in configuration and used in templates to iterate over content.
  • Example usage appears in src/index.njk where collections.news and collections.teamMembers are iterated.
sequenceDiagram
participant Cfg as ".eleventy.js"
participant Coll as "Collections"
participant Tpl as "src/index.njk"
Cfg-->>Coll : Define collections (news, teamMembers, ...)
Tpl->>Coll : Access collections in loops
Coll-->>Tpl : Items with merged data
Tpl-->>Tpl : Render dynamic sections

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)

Dependency Analysis

  • Template dependencies:
    • src/index.njk depends on base layout and multiple macros.
    • Macros depend on datasets passed from global data.
  • Data dependencies:
    • Global datasets (site.json, homepage.json, capabilities.json, testimonials.json, polling.js) are consumed by templates and macros.
    • Per-content data overrides influence permalink generation for specific content folders.
  • Engine and transform dependencies:
    • Nunjucks engine renders templates.
    • Transforms depend on output path and environment (production mode enables html-minifier-terser).
graph TB
Cfg[".eleventy.js"] --> Eng["Nunjucks Engine"]
Eng --> Tpl["src/index.njk"]
Tpl --> Lay["layouts/base.njk"]
Tpl --> Mac["macros/*"]
Tpl --> Dat["_data/*"]
Cfg --> Tr["Obsidian Transform"]
Cfg --> Min["HTML Minify Transform"]
Tr --> Out["_site/*.html"]
Min --> Out

Diagram sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)

Performance Considerations

  • Enable production mode to activate HTML minification.
  • Keep transforms minimal; only apply expensive transforms in production builds.
  • Use filters judiciously; avoid heavy computations inside Nunjucks loops.
  • Leverage Eleventy’s incremental builds and watch targets to reduce rebuild time during development.
  • Place frequently changing assets under passthrough copies to avoid unnecessary processing.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Template rendering errors
    • Verify front matter keys match data keys used in templates.
    • Ensure macros are imported and invoked with correct parameters.
    • Confirm layout paths exist and are correctly referenced.
  • Data-related issues
    • Check that global data files are valid JSON/JS and exported properly.
    • Validate per-content data overrides do not conflict with intended permalink behavior.
    • Inspect async data providers (e.g., polling.js) for proper exports and fallbacks.
  • Transform errors
    • Confirm transforms run only on HTML outputs and environment conditions.
    • Temporarily disable transforms to isolate issues.
  • Build commands
    • Use the development server command to preview changes quickly.
    • Clean the output directory before full builds if stale artifacts persist.

Section sources

  • [.eleventy.js](file://.eleventy.js)
  • [src/index.njk](file://src/index.njk)
  • [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk)
  • [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk)
  • [src/_data/site.json](file://src/_data/site.json)
  • [src/_data/homepage.json](file://src/_data/homepage.json)
  • [src/_data/capabilities.json](file://src/_data/capabilities.json)
  • [src/_data/testimonials.json](file://src/_data/testimonials.json)
  • [src/_data/polling.js](file://src/_data/polling.js)
  • [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json)
  • [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json)

Conclusion

This project’s Eleventy pipeline integrates Nunjucks templating with a robust data cascade, reusable macros, and configurable transforms. Pages like src/index.njk demonstrate how global data, datasets, and collections combine within layouts and macros to produce final HTML. Configuration in .eleventy.js centralizes engines, shortcodes, filters, collections, and transforms, enabling predictable compilation and optimized production output.

[No sources needed since this section summarizes without analyzing specific files]