In every chapter in this book, you’ll need a computer with Node.js and npm (11ty is built with Node.js and runs via npm), a code editor such as VS Code, and access to the book’s GitHub repository for both the starting point code and the finished work. 11ty’s minimum required Node.js version is 14. The code for this book was written and tested with Node 18. Basic knowledge of HTML, CSS, JavaScript, and the command line will also be beneficial.

Before beginning, fork and clone the project’s GitHub repository: https://github.com/PacktPublishing/Eleventy-by-Example.

SSGs have been around since early in the history of web development with systems such as HSC (which stands for HTML Sucks Completely) and Movable Type looking to solve the sometimes problematic developer experience of authoring plain HTML for multi-page sites. These technologies added features such as includes and macros that made creating and maintaining HTML websites much easier.

The other direction development began to move in was rendering templates on the server instead of serving simple HTML back per request. The upside to this was a strong developer experience and the ability to create pages dynamically. Templates were created and uploaded to a server and when a request came from a client, the pages’ HTML was built and sent to the client. This methodology would become the predominant authoring experience for the web over the next decade. With it came longer load times.

SSGs would see a boost in 2008 with...

11ty is an SSG developed by Zach Leatherman in 2017 with a strong sense of inspiration from Jekyll but built in the then-flourishing JavaScript ecosystem. If you know a little Node.js or JavaScript, you can extend the functionality of 11ty. If you don’t have a strong JavaScript background but can run a few commands in the command line, you can use 11ty.

11ty has a few strong philosophies:

• Static-first – While there are new features in 11ty that allow it to run at request time, as well as pre-generate HTML, the strongest use of 11ty will be to create a static site first, and then extend into the server rendering only when necessary.
• Flexible – 11ty doesn’t prescribe one way to create sites. In fact, one of the strongest benefits of 11ty over other SSGs is that it comes bundled with over 10 templating engines that can be used separately or together.
• Frontend agnostic – 11ty doesn’t force you into a single frontend...

While most sites you build with 11ty will require some amount of configuration, 11ty comes packaged with enough defaults to get you up and running without writing any configuration.

To start, from within the cloned GitHub repository, open project-1/chapter-1/start in your code editor. This project has a very basic HTML website. It has an assets directory with CSS and images and an index.html and about.html document with some basic structure and content. If you open index.html in a browser, you’ll get a web page, but it won’t have any styles associated and the anchor to the About page won’t work. That’s because this page is expected to run on a server.

Installing 11ty

In order to get a local server, we’ll install and run 11ty.

First, all Node.js projects need a package.json file. We can create one by running the following:

npm init -y

Running this command will initialize this project as a Node.js...

While 11ty can be run without configuration, a little configuration will make our project cleaner and give us access to additional functionality within 11ty.

To configure 11ty, in our project root, we need a configuration file: eleventy.config.js. At its core, 11ty is a Node.js project. The 11ty configuration file is a JavaScript file that exports a configuration function.

The basic structure of the file is as follows (not project code):

// Create variables that require() any packages we need
const plugin = require('some-eleventy-plugin-package')
// Use module.exports to export a configuration function
module.exports = function(eleventyConfig) {
  // Run any code needed (including built-in 11ty methods)
  // If needed, return an object of configuration
  return {
     // Options here
  }
}

By default, 11ty does not keep track of CSS files, basic JavaScript files, or image files....

One of 11ty’s strengths is also a source of confusion. 11ty comes bundled with 10 templating languages. These languages (including Liquid, Nunjucks, and Handlebars) can be used to create individual pages, includes, and layouts, and can be chained together to create complex systems. While this is incredibly powerful, it can create confusion around terminology.

The 11ty documentation says that layouts “are special templates that can be used to wrap other content.” This doesn’t necessarily clear things up. For this book, we’ll use the following definitions to try to keep things clear:

• Page – an item meant to be rendered as a single URL on the final site, for example, index.html or about.html in this project
• Layout – a file that is used by a page to wrap content in the entire structure for an HTML page
• Include – a file consisting of a small, reusable...

Up to this point, everything we’ve accomplished with 11ty can be replicated in other, smaller tools. Removing the basic HTML boilerplate from each page makes the code much more maintainable and extensible.

To start, we need a new subdirectory in the src directory. Name this directory _templates. By default, 11ty uses an _includes directory for includes and layouts. To avoid semantic confusion, we’ll update our configuration to use the new directory instead.

A note on directory naming

It’s perfectly fine to use the default folder names. Most of my 11ty projects use the _includes naming convention. This step is more for clarity than best practices.

In the configuration function’s return statement, update the dir object to include an includes property:

module.exports = function(eleventyConfig) {
    // Copy `assets/` to `_site/assets/`
    eleventyConfig.addPassthroughCopy...

While the base layout is more maintainable, we can make it easier to reconfigure by breaking the layout down into smaller pieces called includes. These includes will be the beginning of taking the code and turning them into building blocks that can be remixed into different layouts as necessary.

To start, we need to identify the smaller pieces of the base template. Let’s create a header.html file in the src/_templates/includes directory and move all the HTML meta information and visible site header into that file. Everything from the DOCTYPE element to the header element should be removed from base.html and moved into the new file.

While we’re refactoring the header, let’s also move the <nav> element into its own include, as well. 11ty templates can be nested. This means we can include files inside other files. In this case, the header.html include can include navigation.html.

Create a navigation.html file in the includes...

In this chapter, we took a basic HTML website and converted it to an 11ty site. We learned about the philosophies and terminology that are core to understanding 11ty. We ran 11ty with no configuration, then set 11ty up with a best-practice structure using 11ty’s eleventy.config.js configuration file. We repurposed our HTML code into reusable layouts and includes for maintainability and reusability.

To take this chapter further, look at how you might break the header.html include down into smaller, more readable pieces. Maybe abstract out the meta tags into their own include or move the logo SVG into its own file.

In the next chapter, we’ll take a look at 11ty’s powerful Data Cascade and how to add dynamic or unique data to each include as well as to our pages and layouts.

• Full 11ty configuration documentation: https://www.11ty.dev/docs/config/
• CloudCannon’s history of static site generators: https://cloudcannon.com/blog/ssg-history-1-before-jekyll/