Eleventy Tutorial - Create an 11ty Static Site

In this beginner's Eleventy tutorial, we'll learn Eleventy from scratch by creating a simple static website.

We'll learn Eleventy basics and a bit about Static Site Generation, the Jamstack, and Template Engines. Moreover, we'll also learn how to install and set up the prerequisites for Eleventy: Node and npm.

In further articles, we'll learn different concepts of Eleventy, such as working with Front Matter Data, Templates, making a build process, configuration options, and so forth in detail.

Let's get started.

What is a Static Site Generator (SSG)?

A Static Site Generator takes template files, processes them, and then gives output as static files or pages - a complete website that a web browser can understand and display.

One noteworthy aspect of site generators is working with a template engine where most manual coding work is automated and streamlined.

For instance, instead of repetitively writing the same HTML code for each page on your website, you only write it once in a single file and reuse it across all the pages.

There are many site generators available. Some popular ones are Jekyll, Eleventy, Gatsby, Hugo, and Gridsome. They support different web languages (such as JavaScript, Go (programming language by Google), Ruby, etc.) and template engines (such as Nunjucks, Liquid, Markdown, etc.). Here's a comprehensive list of them.

What Is a Template Engine?

A template engine allows you to create the template of your website. So, for instance, instead of writing the same code and copying/pasting that on all site pages, you only write it once in a file and reuse it everywhere. That way, when you make any changes to that file, they are reflected across all the site pages.

It provides us with many benefits, and most importantly, it saves time and prevents potential errors.

You can find a lot of different template engines available, such as Liquid, Mustache, Handlebars, EJS, Pug, etc.

What Is Jamstack?

Because the concept of Jamstack typically involves site generators, you may have heard this term before. Jamstack (previously stylized as JAMStack) stands for JavaScript, API, and Markup. It is not a tool or software. Instead, it is an architectural approach or workflow for creating websites.

A Jamstack website is a decoupled website. It means that the front-end and back-end of the site are separated. The front-end part of the website may rely on several different web languages and tools, while the back-end on the others.

This approach has many benefits, such as better site scalability, increased performance and security, low costs, less maintenance, streamlined developer experience (DX), and many more.

You can read more about it in detail on this website.

What Is Eleventy (11ty)?

Eleventy (also known as 11ty) is a simple JavaScript-based Static Site Generator created by Zach Leatherman that is considered an alternative to Jekyll. It takes a directory of template pages and transforms them into an HTML website.

It stands out from others because it is zero-config and doesn't depend on any client-side JS framework to run. Read more about how it differs in the official docs.

Benefits of Eleventy Over Other SSGs

First, let's discuss how 11ty differs and its benefits compared to other SSGs. It has several benefits, but I've outlined two of them below.

No Framework Requirement

First, you are not limited to using a specific JavaScript framework. Many SSGs require you to use some framework, such as Vue.js or React.js. But with 11ty, you can decide which framework you want to use and if you need one.

You can use vanilla JavaScript, and more importantly, if your website does not need JS at all, you can use Eleventy with just plain HTML and CSS, meaning you can work with Eleventy with little to no knowledge of JS.

Choose Whichever Template Engine You Want to Use

The other benefit is that it allows you to choose which template engines or languages you want to use on your website. You can mix up as many template engines as necessary within your website or page. For example, you could use HTML, Markdown, and EJS altogether.

What Kind of Websites Can You Make with Eleventy?

Thanks to its flexibility and powerful features, you can build most kinds of websites, such as blogs, portfolios, landing pages, e-commerce or online stores, lead capture pages, and others.

Check out some of these popular websites created with Eleventy to see how powerful and flexible it is.

• ESLint
• web.dev
• Netlify
• V8 JavaScript engine
• Foursquare

You can find the complete list of these example websites on the official website of 11ty.

Basic Concepts of Eleventy

Before we move on with the Eleventy tutorial, we need to learn its few basics. In this article, we'll only briefly learn about these features and concepts, as they'll be covered in detail with practical examples in future articles.

If you want to, you can also read about them in detail on its official website.

Templates

A Template is a piece of content or content files (think of a Markdown file that contains your blog text).

Read more about Eleventy Templates: Eleventy Layout and Template Files: A Complete Guide

Layouts

On the other hand, a Layout wraps your template (content or pages).

I know this may confuse you because both; the layout and template mean the same thing in general. However, in Eleventy, they are treated differently.

To put the differences in simple words, an Eleventy Layout is where you can design your site structure and use any template language like HTML or Nunjucks (think of website layout or structure).

While an Eleventy Template is where you can write your website content, such as blog posts, and use any template language like Markdown or HTML (think of website content or text).

Learn more about Eleventy Layouts: Eleventy Layout and Template Files: A Complete Guide

Data

Data is any content that you want to put on your website; this may be your site's URL, name, theme color, and so on. Similarly, it may be the Front Matter Data (see below), like a blog's metadata such as author name, publish date, categories, tags, keywords, etc.

Data Cascade

Eleventy uses a concept of Data Cascade, similar to CSS (Cascading Style Sheets), where data can be supplied from various sources in a cascading form such that some data can supersede other data during the build time. It's a little advanced concept and beyond the scope of this article, which is why I'll cover this in detail in the next articles, where we'll see it in action as well.

Front Matter Data

Front Matter Data is structured data that allows us to provide dynamic data or metadata for each page or post during the site generation process.

Think of blog posts where each post belongs to different authors, publish dates, categories, and so on. This metadata can be supplied using Front Matter Data.

JSON, YAML, and TOML are examples of structured data formats or languages used for supplying this data.

Pagination

In Eleventy, Pagination allows you to iterate over a data set and generate pages/files. This is quite useful if you've got dozens of blog posts, as you can simply provide data (blog posts) in a YAML or other format and let it build out all these pages for you.

What's helpful about this feature is that you can even pull the data from a headless CMS like WordPress.

Collections

Collections allow you to group your content. Think of it as a categorization feature. For instance, you could group all your blog posts in a collection called "posts" as they are posts, and all your static pages in "pages" collections. Collections are created within the Front Matter using tags.

It's important to note that, unlike elsewhere, tags in Eleventy serve only one purpose; to create Collections. For example, WordPress uses tags to create labels for blog posts and other custom post types.

Filters

A Filter is a function that allows you to format your data or content differently. For instance, you could have your blog's title in a JSON file used in Pagination to generate blog posts. Then, during the build, a Filter could be used to ensure that your blog's title is uppercase, lowercase, or formatted in other ways.

Eleventy has several built-in Filters while also allowing you to leverage the existing template languages' Filters.

Shortcodes

Shortcodes allow you to create reusable components that can be used in the Template or Layout files. You may have used or seen them in WordPress, as they are quite commonly used there. You may think of Eleventy Shortcodes in the same way,

Like Filters, Eleventy provides several built-in Shortcodes while allowing you to use template engines' Shortcodes.

Plugins

While you're not required to use any, Eleventy provides many official and community plugins for you to use on your website.

They provide common site features, such as RSS, handling images, running Eleventy for server-side rendering, syntax highlighting, breadcrumb navigation menus, and much more.

You can find the complete list of all of them on the 11ty docs website.

Installing Eleventy Prerequisites

There are two tools you need to install for downloading Eleventy. These are the following.

• Node (or Node.js)
• npm - Node Package Manager (comes pre-installed with recent Node versions)

Node and npm

Node is a JavaScript runtime environment that allows you to run and execute JavaScript outside a web browser.

npm is a tool that allows you to install and manage Node packages. In recent versions of Node, npm comes pre-installed with Node.

Installing Node and npm

Go to the Node.js website and download the Long Term Support version.

Run the installer and follow the setup instructions to install it. You can follow along with the default settings and locations provided by the installer.

Once the installation is complete, run the following command in Windows Terminal or Command Prompt to ensure the installation was successful.

node -v

You should see a version (v16.15.1 as of writing this article) that confirms the installation.

To confirm if npm is also installed, run the following command.

npm -v

If it returns a version (8.19.1 as of writing this article), then npm is also installed.

Let's Get Started with Eleventy Website Tutorial

Now that we're all set up with our prerequisites, it is time to go ahead and create a new directory to set up our website.

Setting up the Project Directory

Launch your preferred source code editor, like Visual Studio Code, create a new folder, and save it. For our tutorial purposes, we'll assume the directory name is eleventy-site. Feel free to name yours whatever you wish to.

This will be our root project folder in which we'll perform all the following operations.

Once done, use the integrated terminal in the editor (CTRL + ~ in Visual Studio Code) to perform the command-line operations mentioned in the following steps.

Initializing npm Project (package.json)

As mentioned above, npm allows us to manage Node packages. To do that, we must initialize (create) an npm project in our working project folder, which will create a package.json file. This package.json file is what you can call the manifest of the project that contains all the essential information, such as dependencies, project metadata (version, author, URL, etc.), and so forth.

Run the following command in the terminal:

npm init -y

This command tells npm to create a package.json file and use the default settings (don't worry, you can change these later).

The output should be similar to the following to confirm that package.json was created successfully.

Wrote to ~\eleventy-site\package.json:

{
  "name": "eleventy-site",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Installing Eleventy

Next, run the following command to download and install Eleventy:

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

This command will begin downloading Eleventy.

The flag -save-dev tells npm to save Eleventy as a dependency of our project.

Once you run the command, you'll see the download progress. Once done, you should see similar output.

added 322 packages, and audited 323 packages in 33s

27 packages are looking for funding
run npm fund for details

found 0 vulnerabilities

Run the following command to confirm that Eleventy was successfully installed.

npx @11ty/eleventy

You should see a similar output to confirm that the installation was successful.

[11ty] Wrote 0 files in 0.02 seconds (v1.0.2)

The output shows that it processed zero files, which is expected because we haven't created anything inside our website folder yet.

The last part of this output (v1.0.2 as of writing this article) shows which version of Eleventy you're currently running.

Creating Our First Website

Next, we'll create an index file in Markdown format (index.md) which we'll compile into a working HTML file (index.html) that the browser can understand and render.

Creating an Index file in Markdown Format

Create a new file in your source code editor and copy and paste the following code.

# Your Eleventy Website

You just created your first Eleventy website.

## This is a Heading

Here's a list of items:

- Item 1
- Item 2
- Item 3
- And so forth.

[This is an example hyperlink](https://w3things.com/ "W3Things - Web Development Guides, Tips, and Resources").

---

Find this compiled `index.html` file in your `_site` folder.

Save the file as index.md in the project root directory.

Compiling the Markdown File into an HTML File

Run the following command to compile your index.md into an HTML file:

npx @11ty/eleventy --serve

As you may have noticed, this is the same command we ran above, with only an addition of the --serve flag. This flag tells Eleventy to watch for changes in the source directory (in our case, the project root folder eleventy-site) and compile the files if changes are detected.

Once the command is executed, you'll see the following output.

[11ty] Writing _site/index.html from ./index.md (liquid)
[11ty] Wrote 1 file in 0.52 seconds (v1.0.2)
[11ty] Watching...
[Browsersync] Access URLs:
 -----------------------------------
    Local: http://localhost:8080
 External: http://192.168.0.108:8080
 -----------------------------------
[Browsersync] Serving files from: _site

As you can see, most of the output is self-explanatory, but let me explain each line.

Line 1 tells where it placed the compiled files (_site/index.html or ~/eleventy-site/_site/index.html in this case) and the source directory from which it took the source files (./index.md or ~/eleventy-site/index.md in this case). Finally, the part in rounded brackets shows the template engine (Liquid in this case).

Line 2 simply tells how much time it took to compile these files.

Line 3 tells that Eleventy is currently watching the source directory (~/eleventy-site in this case) for any changes. This is the result of that --serve flag we used above.

Lines 4-8 tell by which IP address(es) you can access the local site in your web browser. As you can see, it usually provides two addresses; one is the localhost (http://localhost:8080), and the other is your private IP address (http://192.168.0.108:8080).

Line 9 tells from which directory your local site is being served (_site in this case).

You might be wondering what's Browsersync here. It's the plugin behind Eleventy that's serving your website locally. If you're interested, you can read about it here. We'll also be covering Browsersync in our next tutorials.

Accessing the Local Website

To access the site you just created, open your browser, and use one of the Access URLs provided above by Browsersync.

View Original Image Size

Finding the Compiled Files

The compiled files are placed inside the folder _site within the root project directory (~/eleventy-site in our case). Of course, you can change the default input (source) and output (build) locations by creating an 11ty configuration file which we'll discuss in the next articles.

Inspecting Local Eleventy Site Using DevTools

At this point, it's important to note that while we successfully built a website using Eleventy, the above website files, our index file, in this case, contains only the bare minimum to render our site in the web browser.

So, if you open your browser DevTools and inspect the site, you'll notice that our index.html only contains very minimal HTML code.

View Original Image Size

We didn't properly utilize Eleventy's Templates and Layouts system to build our site. So, Eleventy took our Markdown file and compiled it with only the HTML code necessary to render it in the web browser.

In further articles, we'll learn how to use Eleventy Templates, Layouts, and more to build a properly functional and production website.

There you go. You just built your first Eleventy website.

Conclusion

In this beginner's Eleventy tutorial, we learned how to use Eleventy by creating a simple home page while also having learned some of its basic concepts.

If you'd like to dive deep into the concepts, I suggest reading official 11ty docs. Below, I've also provided several additional resources to help you understand Eleventy more in-depth.

Eleventy is a fast, flexible, and powerful site generator that can create almost all types of websites, be it a simple landing page or an e-commerce solution.

Stay tuned as we explore its advanced concepts to see how much we can achieve with it in our next articles.

Have you used Eleventy Static Site Generator yet? If so, how has your experience been with it so far? Let me know your thoughts by sending me an email at [email protected].

Additional Resources

If you're interested in reading more about the technologies and concepts mentioned above, please refer to the following links:

• What is a static site generator? (Source: Cloudflare)
• Understanding client-side JavaScript frameworks (Source: MDN)
• An overview of Markdown markup language (Source: Markdown Guide)