Getting Started with Eleventy

uriByuri JavaScript, Webpack

What is Eleventy?

Eleventy (often written as 11ty) is a simple, flexible static site generator built with JavaScript. Unlike heavier frameworks, Eleventy focuses on doing one thing well: transforming your content and templates into fast, static HTML files. It’s zero-config by default but incredibly customizable when you need it to be.

Think of Eleventy as a tool that takes your content (written in Markdown, HTML, or other formats) and your templates, then combines them to generate a complete website made of static files that can be hosted anywhere.

Why Choose Eleventy?

Eleventy has become increasingly popular for several compelling reasons:

Simplicity: Eleventy works with the languages you already know. There’s no special syntax to learn—just HTML, Markdown, and JavaScript.

Speed: Both your build times and the resulting websites are fast. Eleventy generates plain HTML with no client-side JavaScript required by default.

Flexibility: You can use multiple template languages in the same project (Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml, Pug, and JavaScript Template Literals). Mix and match as needed.

Zero client-side JavaScript: Unlike many modern frameworks, Eleventy doesn’t force any JavaScript on your visitors. You add JavaScript only when you actually need it.

Data-driven: Pull data from APIs, JSON files, or JavaScript files to populate your templates.

Installation and Setup

To get started with Eleventy, you’ll need Node.js installed on your computer. Then, creating a new Eleventy project is straightforward.

First, create a new directory for your project and initialize it:

mkdir my-eleventy-site
cd my-eleventy-site
npm init -y

Install Eleventy as a development dependency:

npm install --save-dev @11ty/eleventy

That’s it! Eleventy is now installed. You can verify by running:

npx @11ty/eleventy --version

Your First Eleventy Site

Let’s create a simple site to understand how Eleventy works. Create a file called index.md in your project root:

# Welcome to My Eleventy Site

This is my first page built with Eleventy!

## Why I'm learning Eleventy

- It's simple and powerful
- It generates fast websites
- It's flexible and unopinionated

Now run Eleventy:

npx @11ty/eleventy --serve

This command does two things: it builds your site and starts a local development server with live reload. Open your browser to http://localhost:8080 and you’ll see your Markdown content transformed into HTML!

Eleventy automatically detected your Markdown file, converted it to HTML, and made it available at the root of your site.

Understanding the Project Structure

As you build your Eleventy site, you’ll typically organize files like this:

my-eleventy-site/
├── _site/              # Generated output (don't edit)
├── _includes/          # Reusable templates and layouts
├── _data/              # Global data files
├── index.md            # Your content files
├── about.md
├── blog/
│   ├── post-1.md
│   └── post-2.md
└── package.json

The _site directory is where Eleventy outputs your generated files. You should add this to your .gitignore. The underscore-prefixed directories (_includes, _data) are special—Eleventy won’t copy them directly to your output.

Creating Layouts

Layouts help you avoid repeating HTML structure. Create a directory called _includes and add a file named base.njk:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
</head>
<body>
    <header>
        <nav>
            <a href="/">Home</a>
            <a href="/about/">About</a>
        </nav>
    </header>
    <main>
        {{ content | safe }}
    </main>
    <footer>
        <p>&copy; 2025 My Eleventy Site</p>
    </footer>
</body>
</html>

Now update your index.md to use this layout by adding front matter at the top:

---
layout: base.njk
title: Home
---

# Welcome to My Eleventy Site

This content now uses a layout!

The {{ content | safe }} in your layout is where your page content gets inserted.

Working with Data

Eleventy makes it easy to work with data. Create a _data directory and add a file called site.json:

{
  "name": "My Eleventy Site",
  "author": "Your Name",
  "description": "Learning Eleventy one step at a time"
}

This data is now globally available in all your templates as site. Update your layout to use it:

<title>{{ title }} - {{ site.name }}</title>

You can also use JavaScript files in _data to fetch data from APIs, compute values, or do anything else JavaScript can do.

Collections: Organizing Related Content

Collections let you group related content. Create a blog post at blog/first-post.md:

---
layout: base.njk
title: My First Blog Post
date: 2025-01-15
tags: post
---

# My First Blog Post

This is the beginning of my blogging journey with Eleventy!

The tags: post makes this part of a “post” collection. Now create blog/index.njk to list all posts:

---
layout: base.njk
title: Blog
---

<h1>Blog Posts</h1>

<ul>
{% for post in collections.post | reverse %}
    <li>
        <a href="{{ post.url }}">{{ post.data.title }}</a>
        <time>{{ post.date.toUTCString() }}</time>
    </li>
{% endfor %}
</ul>

<p><em>Note: We'll learn how to create a custom date filter in the Configuration section below to format dates more nicely!</em></p>

Collections automatically group content by tags, making it easy to create archives, navigation, or related post listings.

Configuration

While Eleventy works with zero configuration, you can customize it with an .eleventy.js file in your project root:

module.exports = function(eleventyConfig) {
    // Copy static assets
    eleventyConfig.addPassthroughCopy("css");
    eleventyConfig.addPassthroughCopy("images");
    
    // Add a custom filter
    eleventyConfig.addFilter("readableDate", dateObj => {
        return new Date(dateObj).toLocaleDateString('en-US', {
            year: 'numeric',
            month: 'long',
            day: 'numeric'
        });
    });
    
    // Now you can use it in templates: {{ post.date | readableDate }}
    
    return {
        dir: {
            input: "src",      // Change input directory
            output: "_site",
            includes: "_includes",
            data: "_data"
        }
    };
};

This configuration file lets you add filters, shortcodes, customize directories, and much more.

Building for Production

When you’re ready to deploy, build your site without the development server:

npx @11ty/eleventy

This generates optimized HTML files in your _site directory. You can deploy these files to any static hosting service like Netlify, Vercel, GitHub Pages, or Cloudflare Pages.

Add these scripts to your package.json for convenience:

"scripts": {
    "start": "eleventy --serve",
    "build": "eleventy"
}

Now you can use npm start for development and npm run build for production builds.

Next Steps

You’ve now learned the fundamentals of Eleventy! Here are some directions to explore next:

Explore template languages: Try Nunjucks, Liquid, or JavaScript templates to see which you prefer.

Add styling: Include CSS files using passthrough copy or explore CSS frameworks.

Create custom filters and shortcodes: Extend Eleventy with your own functionality for common patterns in your site.

Work with dynamic data: Fetch data from APIs at build time to create data-driven static sites.

Optimize images: Use the Eleventy Image plugin to automatically optimize and generate responsive images.

Explore plugins: The Eleventy ecosystem has plugins for RSS feeds, sitemaps, syntax highlighting, and more.

Eleventy’s philosophy is to stay out of your way and let you build sites the way you want. Start simple, and add complexity only when you need it. Happy building!

Essential Resources

Here are the key resources to bookmark as you continue your Eleventy journey:

Official Documentation

Community and Learning

Useful Plugins and Tools

Deployment Platforms

  • Netlify – Popular hosting with automatic deployments
  • Vercel – Fast static hosting with excellent DX
  • Cloudflare Pages – Global CDN with generous free tier
  • GitHub Pages – Free hosting directly from your repository

Stay Updated