Eleventy Adoption Guide: A Complete Framework for Static Site Generation

Eleventy--often stylized as 11ty--represents a fundamentally different approach to static site generation. Unlike frameworks that impose complex build processes and require learning specialized tooling, Eleventy works with your existing content and respects the structure you already have. This comprehensive guide walks you through adopting Eleventy for your next web project, whether you're building a personal blog, documentation site, marketing website, or complex web application.

The philosophy behind Eleventy centers on simplicity and flexibility. Rather than forcing developers into a particular workflow or requiring extensive configuration to get started, Eleventy processes your content files and outputs static HTML that can be deployed anywhere. This approach has earned Eleventy a passionate community and over 19,000 GitHub stars, making it one of the most popular static site generators available today.

What Makes Eleventy Different

Many static site generators come with strong opinions about how you should structure your project, what templating language you must use, and how your build process should work. Eleventy takes a remarkably different stance: it supports multiple template languages without mandating any single approach, works with your project's existing directory structure, and provides sensible defaults that you can customize as needed.

This flexibility means you can use Eleventy for virtually any static content project. Marketing teams appreciate how Eleventy can ingest content from headless CMS solutions while maintaining excellent performance. Developers value the ability to use familiar templating languages like Nunjucks, Liquid, or Handlebars. Content writers can continue using Markdown without learning new syntax. The framework adapts to your needs rather than demanding that you adapt to it.

Performance sits at the core of Eleventy's design philosophy. Because Eleventy generates pure static HTML at build time, the resulting sites load instantly and can be served from any static hosting provider. No client-side JavaScript framework overhead means better Core Web Vitals scores, improved SEO performance, and superior user experiences on slow connections or older devices. This makes Eleventy an excellent choice for building high-performance static websites that prioritize both speed and maintainability.

Getting Started with Eleventy

Prerequisites and Environment Setup

Before installing Eleventy, ensure your development environment meets the basic requirements. Eleventy version 3.1.2 requires Node.js version 18 or higher. You can verify your Node.js installation by running node --version in your terminal. If the command isn't recognized or reports a version below 18, download and install the latest LTS version from the official Node.js website.

Eleventy supports multiple package managers including npm, pnpm, and yarn. This flexibility means you can integrate Eleventy into existing projects regardless of your team's preferred tooling. The installation process remains consistent across package managers, though the specific commands differ slightly.

Initializing Your Project

Create a new directory for your Eleventy project and navigate into it. Initialize a new npm project using your preferred package manager. The initialization command creates a package.json file that tracks your project's dependencies and configuration. For npm users, run npm init -y to accept default values and skip the interactive questionnaire.

Modern JavaScript projects increasingly use ES modules rather than CommonJS. To configure your project for ES modules, run npm pkg set type="module". This setting enables import/export syntax in your JavaScript files and is required for certain Eleventy features and plugins.

Installing Eleventy

With your project initialized, install Eleventy using your package manager. The official package name is @11ty/eleventy, published on npm and available through all major package registries. Installation adds Eleventy to your package.json devDependencies and makes the eleventy command available in your project's context.

npm install @11ty/eleventy

After installation, you can run Eleventy using npx, which executes the local project's version. Running Eleventy without any files to process reports zero output files generated, which is expected behavior when starting a new project. For teams exploring modern JavaScript frameworks and tools, Eleventy offers a lightweight alternative that integrates seamlessly with existing Node.js workflows.

Understanding Eleventy's Architecture

How Eleventy Processes Content

Eleventy operates on a straightforward input-output model that makes its behavior predictable and easy to understand. You specify input directories containing your source files, configure output directories for generated content, and Eleventy transforms input files into output files based on their template language and front matter configuration.

The transformation process respects your directory structure by default, creating corresponding output paths for each input file. A file at src/pages/about.md would generate _site/pages/about/index.html if you follow Eleventy's default conventions. However, you can customize these paths through permalink configurations in your front matter, giving you complete control over your site's URL structure.

Understanding Eleventy's build pipeline helps you debug issues and optimize your build process. When Eleventy runs, it first reads configuration from your eleventy.js file, then discovers all input files, loads any required data files, processes templates through their respective template language engines, applies transforms and filters, and finally writes output files to the designated directory. Each step can be customized through configuration options and plugins.

Directory Structure and Organization

Eleventy works with your existing directory structure rather than imposing its own. This philosophy means you can organize your project files however makes sense for your team and workflow. However, certain organizational patterns have emerged as best practices within the Eleventy community.

A typical Eleventy project separates source files from build output using an input directory (commonly src or the project root) and an output directory (commonly _site or dist). Within the input directory, you might organize content into subdirectories like posts for blog entries, pages for static pages, and includes for reusable template components. Configuration files, data files, and asset directories sit alongside or within these content directories.

The output directory should be excluded from version control since it contains generated files. Add _site or your chosen output directory to your .gitignore file. Your build process regenerates these files from source whenever needed, ensuring your repository contains only the original source files and configuration. This approach aligns with best practices for maintaining clean, version-controlled codebases.

Template Languages and Content Creation

Supported Template Formats

Eleventy distinguishes itself through extensive support for template languages. Rather than requiring you to learn a specific templating syntax, Eleventy allows you to choose from over ten different template languages based on your team's preferences and requirements.

Markdown serves as the most common choice for content-heavy sites. Its lightweight syntax makes writing content comfortable while still supporting basic formatting needs. Eleventy processes Markdown files with front matter, allowing you to add metadata, specify layouts, and configure individual page behavior without leaving your content files.

HTML templates provide maximum flexibility since they're universally understood. You can write plain HTML files with front matter, and Eleventy passes them through with minimal processing. This approach works well for pages requiring precise HTML control or when integrating content from external sources.

Nunjucks brings powerful templating capabilities including loops, conditionals, includes, and filters. Its syntax draws from Jinja2 and Python templating traditions, making it familiar to developers from various backgrounds. Nunjucks excels at reusable components, layout systems, and any template requiring dynamic content manipulation.

Liquid originates from Shopify's templating system and offers similar capabilities to Nunjucks with slightly different syntax. Many developers prefer Liquid for its simplicity and safety guarantees--it intentionally limits template logic to prevent complex business logic from creeping into presentation layers.

Additional supported languages include Handlebars, Mustache, EJS, Haml, Pug, JavaScript templates, and WebC for component-based development. Each language can be configured independently, allowing you to use different languages for different parts of your project if desired. This flexibility makes Eleventy ideal for teams working with diverse technology stacks.

Creating Your First Templates

Begin creating templates by adding front matter to your content files. Front matter--demarcated by triple dashes--contains configuration values that Eleventy uses when processing files. A basic front matter might specify a title, date, and layout template.

---
title: Hello World
date: 2025-01-12
layout: base.njk
---

# {{ title }}

This is my first Eleventy template.

The layout property references a template file in your layouts directory. Layout templates wrap your content, providing consistent headers, footers, navigation, and styling across your site. By extracting these common elements into layouts, you avoid repeating code and maintain consistency as your site grows.

Configuration and Customization

The Eleventy Configuration File

Eleventy reads configuration from a .eleventy.js file in your project root. This JavaScript module exports a configuration function that receives a Eleventy instance, allowing you to customize virtually every aspect of Eleventy's behavior.

The configuration file controls input and output directories, template language registrations, passthrough copies for static assets, filters and transforms, collection definitions, and watch targets for development. Here's a minimal configuration that establishes common defaults:

module.exports = function(eleventyConfig) {
 // Passthrough copy for static assets
 eleventyConfig.addPassthroughCopy("src/assets");
 
 // Add a filter
 eleventyConfig.addFilter("myFilter", function(value) {
 return value;
 });
 
 return {
 dir: {
 input: "src",
 output: "_site",
 includes: "_includes",
 layouts: "_layouts"
 }
 };
};

Directory Configuration

The dir configuration object controls where Eleventy looks for files and where it writes output. The input directory contains your source files--the files Eleventy will process. The output directory receives the generated static site. includes and layouts directories hold reusable template components.

You can customize each directory independently or use defaults that work for most projects. Some teams prefer placing layouts and includes alongside content files for smaller projects, while others maintain separate directories to keep source organization clean. Eleventy supports whatever structure works best for your team.

Passthrough Copies and Asset Management

Static assets like images, CSS files, JavaScript, fonts, and other non-template files need special handling. Rather than processing these files through template engines, Eleventy can copy them directly to the output directory using passthrough copies.

eleventyConfig.addPassthroughCopy("src/assets/css");
eleventyConfig.addPassthroughCopy("src/assets/images");
eleventyConfig.addPassthroughCopy("src/assets/fonts");

You can configure passthrough copies for individual files, entire directories, or patterns matching specific file types. This flexibility allows you to organize assets however you prefer while ensuring they appear correctly in your generated site. For teams focused on performance optimization, Eleventy's straightforward asset handling makes it easy to implement optimized delivery strategies.

Data Management and the Data Cascade

Understanding the Data Cascade

Eleventy's data cascade determines how data flows into your templates. This system layers data from multiple sources, with later sources overriding earlier ones, creating a predictable hierarchy for resolving template data.

The cascade flows from global data files to template directory data, to data files in the same directory, to front matter in individual files. This layering means you can set site-wide defaults in global files, configure section-specific values in directory data files, and override anything in individual front matter as needed.

Global Data Files

Global data files live in a _data directory at your input directory root. These files define data available across your entire site. Eleventy supports JavaScript, JSON, and YAML formats for data files, with JavaScript files allowing dynamic data generation.

// _data/site.json
{
 "title": "My Eleventy Site",
 "description": "A site built with Eleventy",
 "url": "https://example.com"
}

Global data works well for site-wide configuration like navigation menus, social media links, author information, and any other data that multiple templates need to access.

Directory Data Files

Data files placed in subdirectories apply only to content within those directories. A _data folder in your posts directory might define post-specific configuration like default layout, category mappings, or pagination settings.

This capability allows you to maintain different configurations for different sections of your site. Blog posts might use one set of defaults while documentation pages use another, all without managing complex conditional logic in templates.

Computed Data

Computed data files run last in the cascade and can transform or generate data based on all other data sources. Use computed data to calculate values that depend on other data, format dates consistently across your site, or prepare data specifically for template rendering.

// _data/computed.js
module.exports = {
 title: data => `${data.site?.title || 'Site'} - ${data.title || ''}`,
 formattedDate: data => {
 const date = new Date(data.date);
 return date.toLocaleDateString('en-US', {
 year: 'numeric',
 month: 'long',
 day: 'numeric'
 });
 }
};

Computed data receives all other data as its input and returns an object merged into the data cascade. This makes computed data powerful for transforming existing values without modifying source data. Teams building content-rich websites find this capability particularly valuable for maintaining consistent data across large content libraries.

Collections and Content Organization

Built-in Collections

Eleventy automatically creates collections for different content types. The all collection contains every template file in your project, serving as the base for custom collections. Pagination creates implicit collections from paginated data, and template directory data can define collection properties.

Collections provide powerful ways to organize and query your content. You can iterate over collections in templates to generate archives, related content lists, navigation menus, and any other content aggregation your site requires.

Creating Custom Collections

Custom collections organize your content based on custom logic. Define collections using JavaScript functions that return filtered or sorted arrays of content objects.

eleventyConfig.addCollection("posts", function(collection) {
 return collection.getFilteredByGlob("src/posts/*.md").reverse();
});

eleventyConfig.addCollection("featured", function(collection) {
 return collection.getFilteredByGlob("src/posts/*.md").filter(item => item.data.featured);
});

Collections can sort content chronologically, filter by tags or categories, group by custom properties, or implement any logic that helps organize your content. This flexibility enables sophisticated content architecture without requiring a database.

Tags and Filtering

Tags connect content into collections and enable filtering in templates. Add tags through front matter, and Eleventy automatically includes tagged content in the corresponding collection.

---
title: My Blog Post
tags: ["posts", "featured", "javascript"]
---

Content here...

Iterate over tagged content in templates to generate category pages, series listings, or any other grouped content display. This approach scales well for sites with extensive content libraries.

Plugins and Ecosystem

Core Plugins

Eleventy's plugin ecosystem extends the framework's capabilities without bloating the core installation. Core plugins address common needs like image optimization, navigation generation, RSS feeds, and syntax highlighting.

Image Plugin automatically optimizes images during build, generating multiple sizes, modern formats, and responsive markup. This plugin eliminates the need for external image processing tools and ensures your site delivers appropriately sized images to visitors.

Navigation Plugin generates navigation structures from your content hierarchy, supporting dropdown menus, breadcrumbs, and other navigation patterns. The plugin works with your existing content structure rather than requiring separate navigation configuration.

RSS Plugin creates RSS and Atom feed XML from your content collections. This plugin handles the complex XML generation required for standards-compliant feeds that work with all feed readers.

Syntax Highlighting Plugin processes code blocks in your content, adding appropriate CSS classes for syntax coloring. The plugin supports dozens of programming languages and integrates with Prism.js or Highlight.js.

Installing and Configuring Plugins

Install plugins through npm and configure them in your Eleventy configuration file. Each plugin package provides setup instructions and configuration options.

const pluginRss = require("@11ty/eleventy-plugin-rss");

module.exports = function(eleventyConfig) {
 eleventyConfig.addPlugin(pluginRss);
 
 // Plugin configuration...
};

Plugins typically provide additional filters, shortcodes, or collections that you use in your templates. Consult each plugin's documentation for specific usage instructions. The plugin ecosystem allows Eleventy to grow alongside your project without adding unnecessary complexity to the core installation.

Deployment and Hosting

Static Hosting Options

Eleventy generates static files that work with any static hosting provider. The most popular options include Netlify, Vercel, Cloudflare Pages, and GitHub Pages, each offering free tiers suitable for personal projects and production deployments.

Netlify provides excellent Eleventy support with automatic builds from git repositories, form handling, edge functions, and a generous free tier. Netlify's drop-in build system recognizes Eleventy projects automatically and configures appropriate build commands.

Vercel offers similar functionality with particularly strong integration for projects using modern JavaScript features. Vercel's edge network delivers excellent global performance, and the platform handles both build configuration and environment variables seamlessly.

Cloudflare Pages provides the fastest global delivery with Cloudflare's edge network. The platform integrates with Cloudflare's other services including images, analytics, and workers, making it a comprehensive solution for static and hybrid sites.

Build Configuration

Configure your hosting provider to run Eleventy's build command. The standard build command runs Eleventy and outputs files to your configured output directory. Build output directories often need explicit configuration depending on your host's expectations.

{
 "build": {
 "command": "eleventy",
 "publish": "_site"
 }
}

Deploy preview environments let you verify changes before production deployment. Most hosts provide these automatically for pull requests, allowing you to catch issues early in your development workflow. For enterprise deployments, this preview capability ensures stakeholders can review changes before they go live.

Performance Optimization

Build Performance

Eleventy's incremental build capabilities significantly reduce rebuild times during development. Rather than processing all files on every change, incremental builds only process files that changed and files depending on those changes.

Enable incremental builds by running Eleventy with the --incremental flag. This feature works best when your content and templates remain reasonably organized with clear dependencies.

Output Performance

Static HTML from Eleventy loads faster than dynamic pages because there's no server-side processing at request time. Browser caching, CDN delivery, and minimal JavaScript requirements all contribute to excellent performance.

Optimize output performance by minimizing CSS and JavaScript, using appropriate image formats and sizes, and leveraging browser caching through hosting configuration. Eleventy's plugins for image optimization and bundling help with these optimizations. The resulting performance improvements benefit both user experience and search engine rankings.

Migration Considerations

Moving from Other Static Site Generators

Migrating from Jekyll, Hugo, Gatsby, or other static site generators typically involves converting template syntax and reorganizing content to match Eleventy's conventions. The migration effort depends on how heavily you used generator-specific features.

Most content files require minimal changes--primarily updating front matter syntax and template directives. Layouts and components may need more substantial rewriting depending on the templating language differences between generators.

Moving from Traditional CMS

Teams moving from WordPress, Drupal, or other CMS platforms face larger content migration tasks. Export your content to Markdown or HTML, then reorganize files to match Eleventy's structure. Custom fields and complex content types may require data transformation scripts.

Consider using Eleventy's pagination features to generate category, tag, and archive pages from your migrated content. These pages maintain SEO value and navigation patterns your visitors expect. For organizations considering a platform migration, Eleventy offers a clean, maintainable alternative to traditional CMS systems.

Best Practices and Recommendations

Project Organization

Maintain clear separation between source and output directories. Keep layouts, includes, and data files in designated directories rather than mixing them with content. Use consistent naming conventions that make your project's structure immediately clear to new team members. Version control your source files but not your output directory. A clean .gitignore prevents accidentally committing generated files, keeping your repository focused on source code.

Template Conventions

Choose template languages that your team can maintain long-term. While Eleventy supports many options, standardizing on one or two languages reduces cognitive overhead and makes code reviews easier. Document your conventions in a README or contribution guide.

Use layouts consistently to maintain visual coherence across your site. Define base layouts that other layouts extend, creating a clear hierarchy of template inheritance.

Development Workflow

Configure Eleventy's development server with appropriate watch options. The --serve flag starts a local server with hot reload, automatically refreshing browsers when files change. Add watch targets for CSS, JavaScript, and other assets that Eleventy copies rather than processes.

Use environment variables to manage configuration differences between development and production. Eleventy's configuration file can read process environment variables and adjust settings accordingly. Following these practices ensures smooth team collaboration on Eleventy projects.

Conclusion

Eleventy offers a compelling path to static site generation that respects your existing workflows and scales with your project's needs. Its flexibility with template languages, intuitive data cascade, and active plugin ecosystem make it suitable for everything from simple blogs to complex documentation sites. The framework's focus on static output ensures excellent performance and broad hosting compatibility, while its incremental build capabilities keep development fast even as content grows.

Whether you're building your first static site or migrating from another generator, Eleventy provides the tools and flexibility to succeed. Start with the basics--installation, a few templates, and simple configuration--and expand into plugins, custom collections, and advanced features as your project's requirements evolve. The Eleventy community's documentation, plugins, and supportive Discord community ensure help is available when you need it.

For teams evaluating static site solutions, Eleventy stands out as a pragmatic choice that delivers results without unnecessary complexity. Its active development, comprehensive documentation, and welcoming community make it an excellent foundation for any static web project.

Sources

1. Eleventy Official Documentation - The authoritative source for Eleventy features, installation steps, and configuration options
2. LogRocket Eleventy Adoption Guide - Practical adoption guidance with code examples
3. Eleventy GitHub Repository - Community stats and release information