Static Site Generation Architecture

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json) - [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/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk) - [src/_includes/layouts/knowledge.njk](file://src/_includes/layouts/knowledge.njk) - [src/_includes/layouts/iaa-base.njk](file://src/_includes/layouts/iaa-base.njk) - [src/_includes/macros/service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk) - [src/_includes/macros/news-article-card.njk](file://src/_includes/macros/news-article-card.njk) - [src/_includes/macros/team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk) - [src/index.njk](file://src/index.njk) - [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json) - [src/content/team/team.11tydata.json](file://src/content/team/team.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 describes the static site generation architecture built with Eleventy. It explains the content processing pipeline from Markdown and data files through Eleventy’s data cascade to Nunjucks template rendering and final HTML output. It also covers collections, transforms, shortcodes/filters, asset handling, modular CSS integration, and build-time optimizations.

Project Structure

The project follows a conventional Eleventy structure with a clear separation of concerns:

  • Content: Markdown posts under content folders (news, cases, team, services, knowledge)
  • Data: Global and per-collection data under _data
  • Templates: Nunjucks templates and layouts under _includes
  • Assets: CSS, JS, and repository media under assets
  • Build scripts: Eleventy configuration and npm scripts
graph TB
A[".eleventy.js"] --> B["Templates and Layouts<br/>src/_includes/*"]
A --> C["Content<br/>src/content/*"]
A --> D["Global Data<br/>src/_data/*"]
A --> E["Passthrough Assets<br/>src/assets/*"]
B --> F["Output HTML<br/>_site/*"]
C --> F
D --> F
E --> F

Diagram sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Section sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Core Components

  • Eleventy configuration defines directories, template formats, passthrough copy, watch targets, shortcodes, filters, collections, and transforms.
  • Nunjucks layouts and macros encapsulate reusable UI and composition logic.
  • Data files supply global and per-page metadata and content lists.
  • Collections enable cross-page aggregation and sorting of content.

Key responsibilities:

  • Configuration: [Eleventy config:1-283](file://.eleventy.js#L1-L283)
  • Layouts: [Base layout:1-260](file://src/_includes/layouts/base.njk#L1-L260), [IAA base:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99), [Knowledge layout:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • Macros: [Service card:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11), [News card:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35), [Team card:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • Data: [Site metadata:1-20](file://src/_data/site.json#L1-L20), [Homepage content:1-23](file://src/_data/homepage.json#L1-L23), [Capabilities:1-53](file://src/_data/capabilities.json#L1-L53), [Testimonials:1-24](file://src/_data/testimonials.json#L1-L24)
  • Collections: [News:170-174](file://.eleventy.js#L170-L174), [Cases:176-179](file://.eleventy.js#L176-L179), [Newsletters:181-185](file://.eleventy.js#L181-L185), [Team:187-191](file://.eleventy.js#L187-L191), [Featured News:193-198](file://.eleventy.js#L193-L198), [Services:200-204](file://.eleventy.js#L200-L204), [Knowledge:206-210](file://.eleventy.js#L206-L210)
  • Transforms: [Obsidian syntax:217-239](file://.eleventy.js#L217-L239), [HTML minify:242-261](file://.eleventy.js#L242-L261)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/_includes/layouts/iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [src/_includes/layouts/knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • [src/_includes/macros/service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [src/_includes/macros/news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [src/_includes/macros/team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)
  • [src/_data/homepage.json:1-23](file://src/_data/homepage.json#L1-L23)
  • [src/_data/capabilities.json:1-53](file://src/_data/capabilities.json#L1-L53)
  • [src/_data/testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)

Architecture Overview

The build pipeline:

  1. Eleventy reads configuration and sets directories.
  2. Passthrough copy duplicates assets and admin files to output.
  3. Data cascade merges global and per-collection data.
  4. Collections assemble content with sorting and filtering.
  5. Nunjucks renders templates with layouts and macros.
  6. Transforms post-process HTML (Obsidian syntax, minification).
  7. Final HTML and assets are written to _site.
graph TB
subgraph "Configuration"
CFG[".eleventy.js"]
end
subgraph "Inputs"
DATA["Global Data<br/>src/_data/*"]
COL["Collections<br/>src/content/*"]
TPL["Templates & Layouts<br/>src/_includes/*"]
ASSETS["Assets<br/>src/assets/*"]
end
subgraph "Processing"
DC["Data Cascade"]
CL["Collections"]
NJK["Nunjucks Rendering"]
TR["Transforms"]
end
subgraph "Output"
OUT["_site/*"]
end
CFG --> DC
CFG --> CL
CFG --> NJK
CFG --> TR
DATA --> DC
COL --> DC
DC --> CL
CL --> NJK
TPL --> NJK
ASSETS --> OUT
NJK --> TR
TR --> OUT

Diagram sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/_includes/layouts/knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)

Detailed Component Analysis

Content Collections and Relationship to Templates

Eleventy defines several collections that drive page rendering:

  • news: sorted by date descending
  • cases: raw glob
  • newsletters: sorted by date descending
  • teamMembers: sorted by order field ascending
  • featuredNews: filtered by featured flag and sorted by date descending
  • services: sorted by order field ascending
  • knowledge: sorted by date descending

These collections are consumed by templates to render lists and pages. For example, the home page imports multiple macros and iterates over collections and data files to render carousels and teasers.

sequenceDiagram
participant E as "Eleventy"
participant C as "Collections"
participant D as "Data Cascade"
participant L as "Layouts/Macros"
participant O as "Output"
E->>C : "Build collections"
E->>D : "Merge global and per-collection data"
E->>L : "Render templates with layouts and macros"
L-->>O : "HTML output"

Diagram sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [src/index.njk:1-164](file://src/index.njk#L1-L164)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [src/index.njk:1-164](file://src/index.njk#L1-L164)

Nunjucks Template System: Layouts, Macros, and Page Templates

  • Base layout provides the HTML skeleton, meta tags, canonical, Open Graph, Twitter Card, fonts, and shared footer. It injects site metadata and page context.
  • Knowledge layout extends the base for knowledge articles, adding breadcrumbs, metadata, tags, and a back link.
  • IAA base layout is tailored for alliance pages with distinct branding and navigation.
  • Macros encapsulate reusable components:
    • service-capability-card renders capability cards
    • news-article-card renders news items in carousel or article variants
    • team-flip-card renders team member flip cards

The home page (index.njk) demonstrates importing macros and iterating over collections and data to render content sections.

classDiagram
class BaseLayout {
+meta_tags
+canonical
+OG_and_Twitter
+fonts
+footer
}
class KnowledgeLayout {
+breadcrumbs
+metadata
+tags
+back_link
}
class IaaBaseLayout {
+iaa_logo
+iaa_footer
}
class ServiceCardMacro {
+render_card(service)
}
class NewsCardMacro {
+render_card(item, variant)
}
class TeamCardMacro {
+render_card(item)
}
class HomePage {
+imports_macros
+iterates_collections
}
KnowledgeLayout --> BaseLayout : "extends"
HomePage --> ServiceCardMacro : "uses"
HomePage --> NewsCardMacro : "uses"
HomePage --> TeamCardMacro : "uses"

Diagram sources

  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/_includes/layouts/knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • [src/_includes/layouts/iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [src/_includes/macros/service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [src/_includes/macros/news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [src/_includes/macros/team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [src/index.njk:1-164](file://src/index.njk#L1-L164)

Section sources

  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/_includes/layouts/knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • [src/_includes/layouts/iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [src/_includes/macros/service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [src/_includes/macros/news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [src/_includes/macros/team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [src/index.njk:1-164](file://src/index.njk#L1-L164)

Data Cascade and Page-Specific Data

Eleventy’s data cascade merges:

  • Global data from src/_data (e.g., site.json, homepage.json, capabilities.json, testimonials.json)
  • Per-collection data via .11tydata files (e.g., news.11tydata.json, team.11tydata.json)
  • Front matter and computed data per page

The home page consumes global data (homepage.json) and iterates over collections (collections.news, collections.teamMembers) and data arrays (capabilities.items, testimonials.items). The knowledge layout uses front matter (title, date, author, tags_list) and content rendering.

flowchart TD
Start(["Template Render"]) --> Merge["Merge Global Data<br/>src/_data/*"]
Merge --> PerCol["Per-Collection Data<br/>.11tydata files"]
PerCol --> FrontMatter["Front Matter + Page Data"]
FrontMatter --> Collections["Collections<br/>news, teamMembers, etc."]
Collections --> Render["Render with Layouts and Macros"]
Render --> End(["HTML Output"])

Diagram sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)
  • [src/_data/homepage.json:1-23](file://src/_data/homepage.json#L1-L23)
  • [src/_data/capabilities.json:1-53](file://src/_data/capabilities.json#L1-L53)
  • [src/_data/testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
  • [src/content/news/news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [src/content/team/team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)
  • [src/_data/homepage.json:1-23](file://src/_data/homepage.json#L1-L23)
  • [src/_data/capabilities.json:1-53](file://src/_data/capabilities.json#L1-L53)
  • [src/_data/testimonials.json:1-24](file://src/_data/testimonials.json#L1-L24)
  • [src/content/news/news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [src/content/team/team.11tydata.json:1-2](file://src/content/team/team.11tydata.json#L1-L2)

Transforms and Post-Processing

Two transforms are applied:

  • obsidianSyntax: converts wiki links and callouts to HTML inside .html outputs.
  • htmlmin: minifies HTML in production builds.

These transforms run after rendering and before writing to disk.

sequenceDiagram
participant R as "Renderer"
participant T1 as "obsidianSyntax"
participant T2 as "htmlmin"
participant FS as "Filesystem"
R->>T1 : "Apply transform to HTML"
T1-->>R : "Processed HTML"
R->>T2 : "Apply transform to HTML"
T2-->>FS : "Write minified HTML"

Diagram sources

  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Section sources

  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Asset Pipeline and Static Assets

Eleventy is configured to pass through assets and admin files to the output directory. Watch targets are configured for CSS, JS, and data to speed up development rebuilds.

  • Passthrough copy: assets, admin, redirects, robots.txt, favicon.ico, favicon.svg
  • Watch targets: src/assets/css/, src/assets/js/, src/_data/

This ensures that CSS, JS, and images are copied without modification, while Eleventy focuses on transforming content and templates.

flowchart LR
A["src/assets/*"] --> P["Passthrough Copy"]
B["src/admin/*"] --> P
C["src/_redirects"] --> P
D["src/robots.txt"] --> P
E["src/favicon.ico, favicon.svg"] --> P
P --> O["_site/*"]

Diagram sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)

Section sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)

Modular CSS Integration

CSS is organized into modular files under src/assets/css/modules and bundled into main.css. The base layout imports main.css globally, ensuring consistent styling across pages. The modular structure supports maintainability and selective loading where applicable.

  • Import path: main.css is linked in base layout
  • Modules: organized by semantic layers (variables, utilities, components, responsive breakpoints, etc.)

This approach integrates seamlessly with Eleventy’s passthrough copy so compiled CSS remains available in _site.

Section sources

  • [src/_includes/layouts/base.njk:27-27](file://src/_includes/layouts/base.njk#L27-L27)

Build Process and Optimizations

Build scripts orchestrate Eleventy and auxiliary tools:

  • build: runs Eleventy and initializes Pagefind indexing
  • dev: runs Eleventy in serve mode
  • deploy/preview: builds then deploys via Wrangler

Optimizations:

  • HTML minification in production via html-minifier-terser
  • Passthrough copy avoids unnecessary processing of static assets
  • Watch targets reduce rebuild times during development
  • Shortcodes and filters provide runtime helpers for content formatting

Section sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)

Dependency Analysis

Eleventy’s configuration ties together inputs, processing, and outputs. The following diagram highlights key dependencies among configuration, data, collections, and templates.

graph TB
CFG[".eleventy.js"] --> DIR["Directories<br/>input/output/includes/data"]
CFG --> PASSTHROUGH["Passthrough Copy"]
CFG --> WATCH["Watch Targets"]
CFG --> SHORT["Shortcodes/Filters"]
CFG --> COLS["Collections"]
CFG --> TRANS["Transforms"]
DATA["_data/*"] --> DC["Data Cascade"]
COLS --> DC
DC --> TPL["_includes/*"]
TPL --> OUT["_site/*"]
PASSTHROUGH --> OUT
TRANS --> OUT

Diagram sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Performance Considerations

  • Use passthrough copy for static assets to avoid unnecessary transformations.
  • Leverage watch targets to speed up incremental builds during development.
  • Apply HTML minification only in production to keep dev builds fast.
  • Keep transforms minimal and scoped to .html outputs.
  • Organize CSS into modular files to simplify maintenance and enable future bundling strategies.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common areas to check:

  • Layout and macro paths: ensure imports and layout references match actual files
  • Collection globs: verify paths in addCollection match content locations
  • Data file keys: confirm front matter and data keys align with template usage
  • Transforms: ensure transforms run only on .html outputs and are enabled conditionally for production

Relevant implementation references:

  • Layouts and macros: [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260), [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43), [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11), [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35), [team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • Collections: [news:170-174](file://.eleventy.js#L170-L174), [cases:176-179](file://.eleventy.js#L176-L179), [newsletters:181-185](file://.eleventy.js#L181-L185), [teamMembers:187-191](file://.eleventy.js#L187-L191), [featuredNews:193-198](file://.eleventy.js#L193-L198), [services:200-204](file://.eleventy.js#L200-L204), [knowledge:206-210](file://.eleventy.js#L206-L210)
  • Transforms: [obsidianSyntax:217-239](file://.eleventy.js#L217-L239), [htmlmin:242-261](file://.eleventy.js#L242-L261)

Section sources

  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/_includes/layouts/knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • [src/_includes/macros/service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [src/_includes/macros/news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [src/_includes/macros/team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Conclusion

The Eleventy-based static site architecture cleanly separates content, data, and presentation. Eleventy’s data cascade and collections power dynamic rendering, while Nunjucks layouts and macros provide reusable, composable UI. The configuration enables efficient asset handling, targeted transforms, and production optimizations. This foundation supports scalable content management and consistent output across pages, including specialized sections like news, cases, team, services, and knowledge.