Eleventy(11ty) first appeared in 2018, and describes itself as a "simpler static site generator". According to the creator, the inspiration for 11ty was a desire for a utility tool like Jekyll, written in node.
The main core of Eleventy is that it takes templates and outputs HTML. It has a lot of flexibility when it comes to mixing templating languages, and that is one of the main reasons for its popularity.
All that sounds great, but the most important thing about static site generators is that at the end, it's possible to have a blazing fast and lightweight website with a great developer experience.
To get started with this tutorial, you need a terminal application and Node.js installed. If node -v in your terminal returns a version number, you are good to go. You can then set up your project folder on your local machine.
mkdir eleventy-project
cd eleventy-project
mkdir src
Once that is finished, we are going to create an .eleventy.js file in our project root folder. This is our 11ty configuration file. This step is actually optional with 11ty, but we will add some code to our configuration later.
The most basic config simply exports a function which returns some settings. The settings tell 11ty to look in our src folder for our content, templates and other source code, and instructs 11ty to use the dist folder for our HTML output.
module.exports = config => {
return {
dir: {
input: 'src',
output: 'dist'
}
};
};
Next, we can go ahead and install 11ty. It is possible to do a global install, but we will install it locally on a per project basis. We will run 11ty locally using npx. In your root folder, install our 11ty dependency.
npm init -y
npm install @11ty/eleventy
If you are using version control, you can also create a .gitignore file in your root folder, and add the following to it. This will ignore our node modules and HTML output.
# Node modules and output
node_modules
dist
You are now ready to make "Hello, World!" appear on our screen. In our src folder, you can create a markdown file called index.md. Open it in the text editor of your choice, and write "Hello, World!" on line 1.
Now, for the moment of truth, running 11ty on a local server, and seeing our output. From your root folder, run 11ty with the following command.
npx eleventy --serve
If you want, you can add this command to your package.json, and run 11ty as an npm script. Next time you want to run your project, you can simply use npm start in your terminal.
"scripts": {
"start": "npx eleventy --serve"
},
Now, visit http://localhost:8080 and admire your shiny new 11ty website. You might also notice that 11ty has created a dist folder in your project. The folder contains an index.html which corresponds to the index markdown file in your src folder. If you open your editor and take a look, you should see the index.html is now populated by your "Hello, World!".
What if we update our index.md with some new text? Well, let's give it a try. Add some new text, and refresh your browser. The --serve flag on our terminal command tells 11ty to serve the dist folder on a local web server, and also watch for any file changes. You should now see your changes. Cool, right?
Hello, World!
This is my new 11ty website.
And that's it, you have gotten started with Eleventy, and made "Hello, World!" appear on screen. Right about now, you might be wondering what the big deal is, and can't I just create a simple HTML file in the first place?
Well, if you want to stick around a little longer, we can look at some cool 11ty features before we finish. It's also important to remember that at the end of the day, 11ty is just creating those simple HTML files we like so much.
A few lines of text isn't so interesting, so let's try to make one of those templates we mentioned earlier. We will create a base HTML template which will be the boilerplate for all pages on our website.
Nunjucks is a templating language that is powered by JavaScript. It allows us to extend HTML, and use cool things like conditionals and loops. 11ty has Nunjucks built in, so we could create a .njk file for our template, but we want to keep writing HTML files. To do this, we will add the following 3 lines to our config after our return statement.
module.exports = config => {
return {
markdownTemplateEngine: 'njk',
dataTemplateEngine: 'njk',
htmlTemplateEngine: 'njk',
dir: {
input: 'src',
output: 'dist'
}
};
This tells 11ty to process our markdown, data and HTML files with Nunjucks. This means we can now use .html extensions instead of .njk.
One of 11ty's expected directories is _includes. This is where we will create our base template layout.
mkdir src/_includes/layouts
Inside the layouts folder, create a base.html template, and add the following.
<!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>
<h1>{{ title }}</h1>
<main>
{{ content | safe }}
</main>
</body>
</html>
Now, you can see Nunjucks in action, you see a yet undefined variable {{ title }}. We will define this later in our markdown frontmatter. content is an 11ty global variable which refers to the body content of our markdown file, and safe is a filter which allows rendering of HTML tags from our markdown content.
That was a lot of work, so let's reward ourselves by using our new template. Open your index.md, delete everything, and paste the following.
---
title: Hello, World!
layout: layouts/base.html
---
This is my new 11ty website.
The title and layout is our frontmatter, and everything below that is our content. If you aren't running your server, run npm start, and take a look at http://localhost:8080. You should see a page title and heading, both containing "Hello, World!", and our content below the heading. If you inspect elements in dev tools, you will see our markdown content appears as a child of our <main> tags, this is where we defined the content variable in our template.
This is a little more interesting, and now we begin to see the power of 11ty. Static site generators are great for blogs, so let's start our own. Inside the layouts folder, create a blog.html template containing the following. Here, we are using Nunjucks syntax to extend our base template for our blog template.
{% extends "layouts/base.html" %}
<article>{{ content | safe }}</article>
Create a blog.md file in our src folder, and add the following frontmatter.
---
title: Blog
layout: layouts/blog.html
---
This is my new blog.
If you visit http://localhost:8080/blog/, you should see your new blog page which is extending base.html. 👍
It's time to start updating some of our content. Take a look at our index.md again. Visit http://localhost:8080 in your browser, and then update the file with some new text.
---
title: Hello, World!
layout: layouts/base.html
---
This is my new 11ty website. Is my website now automatically updating?
Hopefully, you saw your website automatically update this time, and you didn't have to refresh. This is because Browsersync is injected into our website when 11ty is supplied with HTML boilerplate which contains <head> and <body> tags. Now that 11ty has our base template, it will hot-reload for future edits. Awesome!!!
That's all for this blog. It doesn't even scratch the surface of what is possible with 11ty or other static site generators, but hopefully it gives you a starting point for any future projects or experimentation with 11ty. Thanks for reading. ☕
You can read more web musings on my twitter here.