1. Setting up

12 Mar, 2024

To work on an Eleventy project, you'll need:

Not already familiar with all of these? This post by Tatiana Mac introduces each in detail. (It also introduces the version control system Git, which is useful but optional. Git comes with a learning curve and won't be covered here, so if it's new for you, just skip it for now.) Whether you're using Git or not, don't worry about the final "Installing the Things" section of their post.

This guide assumes that you're brand-new to the command line, Node, Eleventy, and templating languages like Nunjucks, but it's not a full tutorial for those tools - it can't replace their docs and communities, and it doesn't really explore features that Eleventy-Zones doesn't use. (It also won't cover things like basic HTML/CSS or navigating your computer's file system.) It's just a tour of how the pieces fit together in this project in particular.

Scene from the movie "Back to the Future." Doc Brown is showing Marty a large, elaborate town model while apologizing, "please excuse the crudity of this model; I didn't have time to build it to scale or to paint it."

Install Node

See https://nodejs.org/ for details.

(If you already have an older version of Node installed: Eleventy-Zones uses Eleventy v2.0.1, which requires Node v14 or newer.)

Download Eleventy-Zones

Visit https://codeberg.org/cypressSap/11ty-zones/releases/latest and download the file labeled "Source code (ZIP)."

(Want to be a courageous canary tester and try out Eleventy v3 early? Download the latest Eleventy-Zones pre-release instead - it's already set up as an ESM-first project on an Eleventy v3 pre-release. If you already have an older version of Node installed, do note that Eleventy v3 requires Node v18 or newer.)

Inside is our project folder, 11ty-zones. Extract this wherever you'd like. (You can rename it if you want, but this guide will continue calling it 11ty-zones.)

Get into the terminal

We'll need to navigate a terminal to the project folder. If you aren't already familiar with using commands like cd ("change directory"), don't worry - there's probably a shortcut you can use instead! Here are some common ones:

When it's ready, the terminal will display a prompt (as in "prompting you for a command"), which might look something like this (PowerShell on Windows):

PS C:\Users\cypressSap\Desktop\11ty-zones>

Or like this (Terminal on macOS):

cypressSap@Big-Macintosh 11ty-zones %

The specifics vary, but the important part is it should include the name/path of terminal's current working directory, confirming that we'll be running commands in our project folder. This guide will show the prompt as simply:

11ty-zones $

Install Eleventy

Like virtually all Eleventy projects, our project is a Node package, and so has a package.json file describing itself. This includes a list of dependencies - other packages, and what versions of those packages, that our package relies on. (In turn, dependencies often have their own dependencies. Node comes with a package manager, called npm, which handles all these for us.)

So next, type (or paste) the command npm install into the terminal and press ⏎ Enter to run it. This tells npm to download our dependencies (namely, Eleventy) and save them into the project. When it's done, the terminal output should look something like this:

11ty-zones $ npm install

added 217 packages, and audited 218 packages in 3s

44 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
11ty-zones $

...and our project folder should now contain a new folder, node_modules. You usually won't need to touch this (that's the package manager's job!) - just know that it's where all of those newly-added packages live.

(By default, despite the word "install" in the command we just used, Node packages aren't actually installed globally on your system; they're downloaded locally to the package you're working in. That may seem weird at first, but it avoids conflicts when different packages need different versions of the same dependency.)