Introduction to Eleventy, a Modern Static Website Generator

I entered the world of Jamstack and static site generators when I launched a page with Publii and Netlify some time back. Since then the term Jamstack has been knocked back by Netlify. Nevertheless, most sites don’t need dynamic pages from a server, and can just be what the web was always supposed to be: linked pages of HTML and CSS, with a little help from JavaScript. Publii is an all-in-one static website creator, which is a great solution if you don’t want to touch any code. But with a little effort you can produce faster, more polished sites using modern web components and having more control over the process. So Eleventy (often shortened to 11ty) is yet another entry in the bag of strangely named JavaScript tools. But what does it offer as a static site generator? Apart from comprehending many templating languages, I note that many of the claimed advantages are things that only make sense if you are already familiar with limitations in other systems. So I’m going to dive in and take a look, explaining as I go. This post assumes that you may be up for updating your own site, but that you don’t do this type of stuff for a living. (I’ll leave out making the site public, since I covered that in the Netlify post.) Eleventy has what I very much like to see, instructions for a quick start. It also uses Markdown straight out of the tin. First of all, I assumed I would have to update my Node.js, which seems to be how I start all things with JavaScript these days. To my surprise, after opening my Warp terminal I already had more than the version 14 required: OK, so as directed I made a directory, created a blank package.json and let npm install what was needed: Great. Now we’ll create two different types of content file (or template) and watch what Eleventy does with them. As directed, I produced these on the command line. This first example is straight HTML which, as it stands, needs no further processing. And this is Markdown. So lets execute Eleventy and see what it does: It created a _site output directory, converted the Markdown into HTML for me, and pushed the index.html straight into it. If we look at the new _site directory, it confirms that: So it treated the output of my README.md file as a new path, with its own default index page. It also seemed to use Liquid, a template language, to work out what to do with the files. So let’s look at the site in a local server:

npx @11ty/eleventy --serve
[11ty] Writing _site/README/index.html from ./README.md (liquid)
[11ty] Writing _site/index.html from ./index.html (liquid)
[11ty] Wrote 2 files in 0.51 seconds (v2.0.1)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

As expected, we get a page at http://localhost:8080 with a solitary “Hi” and a page at http://localhost:8080/README with the words “Page Header” wrapped in <h1>. You can leave this process to “hot load” new pages, and Ctrl-C when you want to restart. So getting the basics up and running is easy, and the results are a sensible output structure. And this was all from the guide. (We could also have made an input source directory).

Template Languages and Front Matter

Now for the interesting stuff. For a personal website, we will want our pages to share a layout. We want to keep our content in Markdown, and let Eleventy make the site for us. There are two useful concepts that Eleventy uses to do this. Template languages allow you to intersperse your intended output language (HTML for a website) with code instructions. We generally need to differentiate between lines that are “this is code, just leave it be” and lines that are “put the result of this on the screen.” As we saw, Eleventy uses the Liquid template by default. So here is some simple Liquid, that shows all the bits: This is a simple if conditional statement that wraps some HTML, which includes a reference. So the code bits check for the existence of a variable called username. If that variable exists, we print this username as the HTML suggests, using the double brackets to indicate that we want the result on screen. I can put this straight into my source template file index.html page and run it. It will be blank though, because the username doesn’t exist. But I can assign one: If you save, and still have the server going, you will see this in your browser: So now we smoothly segue into the other useful concept shared by all templates: front matter. This allows us to define variables (or metadata) in any template, like we did for Liquid. If we alter the source index.html again, the front matter declaration also declares David as a username: And we can also do that in Markdown.

Creating the Website

OK, so let’s get back to our website. A reminder:

• We want pages of our website to use a layout.
• But we only want to write content in Markdown, not hack through HTML.

First of all, I asked ChatGPT to “create an HTML template with a nice cat image.” The result was the following: If I replace our index.html page with this, immediately we see a nice page with a cat: But we want this as our layout page. We want the actual title of our page to appear where “Nice Cat Page” appears, and we want to put some actual text content just under the cat. So let’s rename this cat page layout.html, and alter it to put in Liquid template variables for what we want. Here… …and here: Unlike the variable title, the variable content is a special one that Eleventy is tracking. It understands that when using a layout, any page content goes at this place. But if we just go with this, Eleventy will think the layout page is just a path like README. So we put it in a special folder called _includes which won’t get built, but can be referenced. If we clean out the _site directory (old pages will stick around) and ignore the massive node-modules directory, you should have this: As there is no opening index.html, nothing will be served. All we have is the old README. So let’s make an index.md, tell it about the title and content, and the layout. We use front matter for this: Simple. The built result is this as the index page: Note that a different place kitten is served. And the final directory layout is: This should be enough to stir some enthusiasm in you to write your own site, or perhaps be enough to put you off. However, you will need to go deeper than this to get all the nice components of a modern site, and I will do this in a later post. The takeaway, for now, is that Eleventy gives us a nice flowing process that works with existing technologies while steering us into good practices.