Eleventy Configuration and Setup

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [.eleventyignore](file://.eleventyignore) - [package.json](file://package.json) - [README.md](file://README.md) - [src/_data/site.json](file://src/_data/site.json) - [src/_includes/layouts/base.njk](file://src/_includes/layouts/base.njk) - [src/index.njk](file://src/index.njk) - [src/_data/polling.js](file://src/_data/polling.js) - [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json) - [src/content/news/news.11tydata.json](file://src/content/news/news.11tydata.json) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [netlify.toml](file://netlify.toml) - [wrangler.jsonc](file://wrangler.jsonc)

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
  10. Appendices

Introduction

This document explains the Eleventy configuration system used by the project. It covers the main configuration file structure, passthrough copy settings for static assets, watch targets for development, directory mappings, build directory structure, template format configuration, environment-specific settings, and production optimizations. Practical examples show how to add new passthrough copies, configure watch targets, and set up custom directories. Finally, it describes how configuration integrates with the overall build and deployment pipeline.

Project Structure

The Eleventy project organizes content under a dedicated input directory with explicit includes, data, and layouts directories. The build output is published to a separate directory, while static assets are managed via passthrough copy and watched during development.

graph TB
A[".eleventy.js<br/>Configuration"] --> B["dir.input = src"]
A --> C["dir.output = _site"]
A --> D["dir.includes = _includes"]
A --> E["dir.data = _data"]
A --> F["dir.layouts = _includes/layouts"]
B --> G["src/index.njk<br/>Template"]
B --> H["src/_data/site.json<br/>Global data"]
B --> I["src/_includes/layouts/base.njk<br/>Layout"]
B --> J["src/assets/<br/>Static assets"]
B --> K["src/admin/<br/>CMS admin"]
B --> L["_redirects<br/>Netlify-style redirects"]
M["Passthrough Copy"] --> N["Copied to _site/assets/"]
M --> O["Copied to _site/admin/"]
M --> P["Copied to _site/_redirects"]
M --> Q["Copied to _site/robots.txt"]
M --> R["Copied to _site/favicon.ico"]
M --> S["Copied to _site/favicon.svg"]
T["Watch Targets"] --> U["src/assets/css/"]
T --> V["src/assets/js/"]
T --> W["src/_data/"]
X["Build Output"] --> Y["_site/<br/>Static site"]
Z["Scripts"] --> AA["npm run build<br/>Eleventy + Pagefind"]
AA --> X

Diagram sources

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

Section sources

  • [.eleventy.js:267-282](file://.eleventy.js#L267-L282)
  • [README.md:80-156](file://README.md#L80-L156)

Core Components

  • Passthrough copy: Copies static assets and admin assets directly into the output directory without processing.
  • Watch targets: Adds directories to Eleventy’s file watcher for live reload during development.
  • Shortcodes and filters: Reusable helpers for templates.
  • Collections: Predefined content groupings for templates.
  • Transforms: Post-processing steps applied to output HTML.
  • Directory mappings: Defines Eleventy’s input/output/include/data/layout locations.
  • Template formats: Enables Nunjucks, Markdown, and HTML processing.
  • Environment-specific transforms: HTML minification in production.

Section sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)
  • [.eleventy.js:27-40](file://.eleventy.js#L27-L40)
  • [.eleventy.js:46-164](file://.eleventy.js#L46-L164)
  • [.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)
  • [.eleventy.js:267-282](file://.eleventy.js#L267-L282)

Architecture Overview

Eleventy reads templates and content from the configured input directory, resolves includes and data, renders pages, applies transforms, and writes the final site to the output directory. Static assets are copied via passthrough copy. During development, watch targets trigger rebuilds. Production builds enable HTML minification and Pagefind indexing.

sequenceDiagram
participant Dev as "Developer"
participant Eleventy as "Eleventy CLI"
participant Config as ".eleventy.js"
participant FS as "File System"
participant Out as "_site/"
Dev->>Eleventy : "npm start" or "eleventy --serve"
Eleventy->>Config : Load configuration
Config->>FS : Register passthrough copy paths
Config->>FS : Register watch targets
Eleventy->>FS : Read src/ (templates, content, includes, data)
Eleventy->>Out : Render and write output
FS-->>Eleventy : Trigger rebuild on watched file change
Eleventy-->>Dev : Live reload feedback

Diagram sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)
  • [package.json:5-12](file://package.json#L5-L12)

Detailed Component Analysis

Passthrough Copy Configuration

Passthrough copy ensures static assets and admin assets are copied directly into the output directory without Eleventy processing. This is essential for preserving asset paths and enabling CMS and admin tooling.

  • Copies entire directories and specific files with destination mapping.
  • Examples include assets, admin interface, Netlify-style redirects, and favicon files.

Practical example: To add a new static asset directory, register a passthrough copy mapping in the configuration.

Section sources

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

Watch Targets for Development

Watch targets expand Eleventy’s file watching beyond templates to include stylesheets, scripts, and global data. This enables live reload during development.

  • CSS and JS directories are watched for style and script changes.
  • Global data directory is watched to reflect content changes immediately.

Practical example: To monitor additional directories (e.g., fonts or icons), add a new watch target in the configuration.

Section sources

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

Directory Mappings

The directory mappings define where Eleventy looks for templates, includes, data, and layouts, and where it writes output.

  • Input directory: source of templates and content.
  • Output directory: static site build target.
  • Includes directory: shared template fragments.
  • Data directory: global data files.
  • Layouts directory: reusable page layouts.

These settings align with the project’s folder structure and are referenced by templates and layouts.

Section sources

  • [.eleventy.js:267-274](file://.eleventy.js#L267-L274)
  • [README.md:80-156](file://README.md#L80-L156)

Template Format Configuration

Eleventy supports multiple template formats. The configuration specifies which formats are processed and which engine renders them.

  • Template formats include Nunjucks, Markdown, and HTML.
  • Engines are set for HTML and Markdown rendering.

This allows mixing content types seamlessly.

Section sources

  • [.eleventy.js:275-277](file://.eleventy.js#L275-L277)

Environment-Specific Settings and Production Optimizations

Production builds apply additional optimizations and transforms.

  • Environment detection: production mode is determined by an environment variable.
  • HTML minification: enabled in production to reduce payload size.
  • Build pipeline: Eleventy runs first, followed by Pagefind indexing.

Practical example: To enable production optimizations locally, set the environment variable accordingly before building.

Section sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [package.json:6](file://package.json#L6)

Obsidian Syntax Transform

The project includes a transform that converts Obsidian-style wiki links and callouts into styled HTML during output processing. This transform runs on HTML files and modifies content accordingly.

Practical example: When writing knowledge base articles in Obsidian, rely on this transform to convert wiki links and callouts to styled HTML.

Section sources

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

Collections and Data Integration

Collections aggregate content for templating, and global data is made available to all templates. These integrate with the directory mappings and template formats.

  • Collections: news, cases, newsletters, team members, featured news, services, knowledge.
  • Global data: site metadata, testimonials, clients, IAA partners, affiliations, resources, polling data.

Templates reference collections and data using Nunjucks syntax.

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/polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [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)

Practical Examples

Adding a New Passthrough Copy

Steps:

  1. Determine the source path under the input directory.
  2. Decide the destination path inside the output directory.
  3. Register a passthrough copy mapping in the configuration.

Example reference:

  • [Add a passthrough copy mapping:11-14](file://.eleventy.js#L11-L14)

Configuring Additional Watch Targets

Steps:

  1. Identify directories containing assets or data that should trigger rebuilds.
  2. Add watch targets in the configuration.

Example reference:

  • [Add a watch target:19-21](file://.eleventy.js#L19-L21)

Setting Up Custom Directories

Steps:

  1. Create the new directories under the input directory.
  2. Update directory mappings in the configuration to reflect new locations.
  3. Reference the new directories in templates and layouts.

Example reference:

  • [Directory mappings:267-274](file://.eleventy.js#L267-L274)

Relationship Between Configuration and the Build Process

The configuration defines how Eleventy discovers and processes content, how it watches for changes, and how it optimizes output. The build process integrates with external tools and deployment targets.

flowchart TD
Start(["Start Build"]) --> LoadConfig[".eleventy.js<br/>Load configuration"]
LoadConfig --> DirMap["Apply directory mappings"]
LoadConfig --> Passthrough["Register passthrough copy"]
LoadConfig --> Watch["Register watch targets"]
LoadConfig --> Formats["Configure template formats"]
LoadConfig --> EnvCheck{"Is production?"}
EnvCheck --> |Yes| Minify["Enable HTML minification transform"]
EnvCheck --> |No| SkipMinify["Skip minification"]
DirMap --> ReadSrc["Read templates, includes, data"]
Passthrough --> CopyAssets["Copy static assets to output"]
Watch --> DevMode["Development mode with live reload"]
Formats --> Render["Render templates"]
Minify --> Render
SkipMinify --> Render
Render --> WriteOut["Write to output directory"]
CopyAssets --> WriteOut
DevMode --> WriteOut
WriteOut --> Pagefind["Run Pagefind indexing"]
Pagefind --> End(["Build Complete"])

Diagram sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)
  • [.eleventy.js:267-282](file://.eleventy.js#L267-L282)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [package.json:6](file://package.json#L6)

Dependency Analysis

Eleventy’s configuration interacts with scripts, ignore rules, and deployment configurations. Understanding these relationships helps avoid unintended file inclusion or missing assets.

graph TB
A[".eleventy.js"] --> B["package.json<br/>scripts"]
A --> C[".eleventyignore"]
B --> D["cloudflare-pages.toml<br/>Pages config (deprecated)"]
B --> E["netlify.toml<br/>Netlify config"]
B --> F["wrangler.jsonc<br/>Workers assets binding"]
A --> G["src/_data/site.json<br/>Global data"]
A --> H["src/_data/polling.js<br/>Dynamic data"]
A --> I["src/_includes/layouts/base.njk<br/>Layout"]
A --> J["src/index.njk<br/>Template"]

Diagram sources

  • [.eleventy.js:267-282](file://.eleventy.js#L267-L282)
  • [package.json:5-12](file://package.json#L5-L12)
  • [.eleventyignore:1-7](file://.eleventyignore#L1-L7)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)
  • [src/_data/polling.js:1-17](file://src/_data/polling.js#L1-L17)
  • [src/_includes/layouts/base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [src/index.njk:1-164](file://src/index.njk#L1-L164)

Section sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [.eleventyignore:1-7](file://.eleventyignore#L1-L7)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)

Performance Considerations

  • Enable production mode to activate HTML minification.
  • Keep passthrough copy limited to necessary assets to reduce output size.
  • Use watch targets judiciously to avoid unnecessary rebuilds.
  • Consider splitting large CSS/JS into smaller chunks to improve caching and load performance.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions related to configuration:

  • Static assets not appearing in output:

    • Verify passthrough copy mappings and ensure the source paths exist.
    • Confirm the output directory is correctly mapped.

  • Changes to assets not triggering rebuilds:

    • Add the asset directory to watch targets.

  • Unexpected files included in build:

    • Review ignore rules and adjust as needed.

  • Production optimizations not applied:

    • Ensure the environment variable is set for production and confirm the transform registration.

Section sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)
  • [.eleventyignore:1-7](file://.eleventyignore#L1-L7)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Conclusion

The Eleventy configuration centralizes how the project discovers content, manages static assets, watches for changes, and optimizes output for production. By understanding directory mappings, passthrough copy, watch targets, template formats, and environment-specific transforms, contributors can efficiently extend the build system and maintain a fast, reliable development and deployment pipeline.

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

Appendices

Appendix A: Directory Mappings Reference

  • Input: Source of templates and content.
  • Output: Target directory for the built site.
  • Includes: Shared template fragments.
  • Data: Global data files.
  • Layouts: Page layouts.

Section sources

  • [.eleventy.js:267-274](file://.eleventy.js#L267-L274)

Appendix B: Template Formats Reference

  • Nunjucks, Markdown, HTML are supported.
  • Engines are configured for HTML and Markdown rendering.

Section sources

  • [.eleventy.js:275-277](file://.eleventy.js#L275-L277)

Appendix C: Build and Deployment Pipeline

  • Build command runs Eleventy and then Pagefind indexing.
  • Deployment uses Cloudflare Workers with assets bound to the output directory.

Section sources

  • [package.json:6](file://package.json#L6)
  • [wrangler.jsonc:9-12](file://wrangler.jsonc#L9-L12)