Eleventy Tutorial for Beginners: Build Your First Blazing Fast Static Site

If you’ve ever felt overwhelmed by the sheer size of modern web frameworks, you’re not alone. I spent years jumping between React-based static generators only to realize that for most content-heavy sites, I was shipping way too much JavaScript to the browser. That’s why I switched to 11ty. In this eleventy tutorial for beginners, I’m going to show you how to build a site that is fast by default and gives you total control over your HTML.

Before we dive in, it’s important to understand why use a static site generator in the first place. Unlike WordPress, which builds pages on the fly using a database, Eleventy pre-renders your pages into HTML files at build time. This means your site loads instantly and is virtually unhackable.

Core Concepts of Eleventy

The magic of Eleventy (often called 11ty) is that it is zero-config by default. Unlike other tools, it doesn’t force a specific templating language on you. I’ve found this to be its greatest strength because you can mix and match formats.

Template Agnostic: You can use Markdown for posts, Nunjucks for layouts, and Liquid for snippets—all in the same project.
Zero Client-Side JS: By default, 11ty ships zero JavaScript to the browser. If you want interactivity, you add it yourself manually.
Data Cascades: 11ty allows you to define data in global files, directory-level files, or the front matter of individual pages.

Getting Started with 11ty

To follow this guide, you’ll need Node.js installed on your machine. I recommend using the LTS version to avoid compatibility issues.

Diagram showing the Eleventy build process from source files to static HTML output

1. Initialize Your Project

Open your terminal and run the following commands to create a new directory and initialize your project:

mkdir my-11ty-site
cd my-11ty-site
pm init -y
pm install @11ty/eleventy --save-dev

2. Creating Your First Page

Create a file named index.md in your root folder. Add some simple front matter and content:

---
title: Welcome to my 11ty Site
---
# Hello World!

This is my first site built with Eleventy. It's incredibly fast!

3. Running the Dev Server

Now, let’s see it in action. Run the following command in your terminal:

npx @11ty/eleventy --serve

Eleventy will create a _site folder and start a local server. Open http://localhost:8080 in your browser, and you’ll see your rendered Markdown page. As shown in the workflow diagram below, 11ty takes your raw files and transforms them into a static output folder.

Building Your First Project Structure

As your site grows, putting everything in the root becomes messy. In my experience, a clean structure is key to maintaining a project long-term. Here is the architecture I recommend for beginners:

my-11ty-site/
├── src/
│   ├── _includes/
│   │   └── layout.njk
│   ├── posts/
│   │   └── hello-world.md
│   └── index.md
├── .eleventy.js
└── package.json

Creating a Layout

To avoid repeating your HTML header and footer on every page, create a layout file at src/_includes/layout.njk:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ title }}</title>
</head>
<body>
    <main>
        {{ content | safe }}
    </main>
</body>
</html>

Now, tell your index.md to use this layout by adding it to the front matter:

---
layout: layout.njk
title: Home Page
---
Welcome to my home page!

Finally, update your .eleventy.js config file to tell 11ty to look in the src folder:

module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "_site"
    }
  };
};

Common Mistakes Beginners Make

When I first started with 11ty, I hit a few walls that you can easily avoid:

Forgetting the | safe filter: In Nunjucks, if you don’t use {{ content | safe }}, 11ty will escape your HTML tags, and you’ll see raw code on your page instead of rendered elements.
Over-complicating the Data Cascade: Don’t put everything in global data. Start with page-level front matter and only move to global files when you see a pattern.
Ignoring the Build Step: Remember that changes in your source files need to be built into the _site folder before they can be deployed.

Your Learning Path

Once you’ve mastered the basics of this eleventy tutorial for beginners, I suggest following this progression to become an 11ty pro:

Collections: Learn how to group posts (e.g., a “blog” collection) to create archive pages.
Pagination: Use 11ty’s built-in pagination to handle hundreds of posts across multiple pages.
Shortcodes: Create reusable components (like a YouTube embed or a custom alert box) using JavaScript.
Deployment: Now that your site is built, look into deploying to GitHub Pages (the process is very similar for 11ty).

If you’re debating between different static tools, you might find my comparison of Hugo vs Jekyll for documentation useful, as it highlights the performance trade-offs you’ll encounter as you scale.

Essential Tools for 11ty Development

Tool	Purpose	Why it’s useful
VS Code	Editor	Excellent Nunjucks and Markdown extensions.
Netlify	Hosting	Seamless 11ty integration and automatic builds.
Markdown All in One	Extension	Speeds up content creation with shortcuts.

Ready to take your site live? I highly recommend trying Netlify or Vercel for the easiest deployment experience. If you have any questions about your specific setup, leave a comment below!