Making a Simple Web Site with the Simplest Static Site Generator, Level 1

January 24, 2018

Introducing Eleventy, the simplest and most intuitive static site generator. With Eleventy, you can build data-driven sites quickly and easily — focused on long lasting content that’s easy to maintain. Make your website last 10 years, not 10 months.

Level 1—Data driven templates (You are here)
Level 2—Adding filters

Installation

If you don’t already have it, install node.js and npm (they’re available as a single package). Eleventy requires at least anode --version of 8.0.0 or higher.
Next, install the Eleventy command line utility, available on the lovely npm: npm install -g @11ty/eleventy

Getting Started

Let’s make a web site for our GIF collection. A front end for our own personal bukk.it. Let’s call it Giffleball.

Full finished source code for Level 1 of this tutorial is available on GitHub.

Create the files

Make a directory for our beautiful new web site. (Do not include the ~ $ when running the command)

~ $ mkdir giffleball

Let’s add some images to our site. Attached here are a choice selection of bird-themed GIF-gems from the esteemed bukk.it itself.

Save these image files into an img folder inside of ourgiffleball directory.

 giffleball/
+  img/             *new
+    ???.jpg        *new
+    ….jpg          *new
+    parrot.gif     *new

Create a template

Let’s make a template! Create a file called index.html in the giffleball directory.

 giffleball/
+  index.html       *new
   img/
   	???.jpg
     ….jpg
     parrot.gif

Let’s add a list with some links to our GIFS to the index.html file:

<!doctype html>
<html lang="en">
 <head>
  <meta charset="utf-8">
  <title>Giffleball</title>
 </head>
 <body>
  <h1>Giffleball</h1>
  <ul>
   <li><a href="img/???.jpg">???.jpg</a></li>
   <li><a href="img/….jpg">….jpg</a></li>
   <li><a href="img/parrot.gif">parrot.gif</a></li>
  </ul>
 </body>
</html>

So far, nothing special going on here. But, we can run eleventy and generate our site anyway. We’ll pass in the extensions that we want eleventy to process with--formats.

~ $ cd giffleball
~/giffleball $ eleventy --formats=html,gif,jpg
Writing _site/index.html from ./index.html.
Wrote 1 file in 0.07 seconds

This created our new web site in the _site directory. If you want it to go somewhere else, simply pass a new directory to --output:

~/giffleball $ eleventy --output=somewhereelse
Writing somewhereelse/index.html from ./index.html.
Wrote 1 file in 0.07 seconds

Make it Data Driven

Okay, so far we could have just loaded up our index.html in the browser and it would have looked the same. The output matched the input. So, let’s layer on some eleventy things. Let’s move some of the site data into our front matter:

+---
+title: Giffleball
+images:
+  - ???.jpg
+  - ….jpg
+  - parrot.gif
+---
 <!doctype html>
 <html lang="en">
  <head>
   <meta charset="utf-8">
   <title>{{ title }}</title>
  </head>
  <body>
   <h1>{{ title }}</h1>
   <ul>
   {% for filename in images %}
    <li><a href="img/{{ filename }}">{{ filename }}</a></li>
   {% endfor %}
   </ul>
  </body>
 </html>

We’ve moved our site’s title (used in two different places) to our front matter and the list of images as well.

By default in Eleventy, the liquid templating engine syntax is available on HTML and Markdown files. Eleventy supports a wide variety of templating engine syntaxes (peep the full list), and those are available when you use specific file extensions. For example, our index.html could have been named index.liquid and it would be functionally equivalent:

~/giffleball $ mv index.html index.liquid
~/giffleball $ eleventy --formats=liquid,html,jpg,gif
Writing _site/index.html from ./index.liquid.
Wrote 1 file in 0.07 seconds

We also allow you to change the defaults, of course, but we’ll get to that in a future tutorial (or you can skip ahead and peep the README).

Using a templating engine has a few benefits:

Change your data in one place. To change our site’s name, we can do it in one place (the front matter) instead of two. To add or remove images, we don’t have to edit the template HTML.
Change the markup for your image links once. Say we wanted to modify the HTML for our list items. Because we’re data-driven here, we can modify our template HTML in our loop instead of having to modify three or more <li> entries individually. Three isn’t bad. But what if our site grows to 300 images?
Special characters in the file names. Looking in the browser, it seems like ???.jpg isn’t really playing nice with my web server. The file doesn’t show up correctly. What if our file names have weird characters that aren’t supported by our web browser or web server? We need to escape them! The Liquid templating syntax has just the thing: a url_encode filter. Let’s update our template to use it:
```
{% for filename in images %}
  <li><a href="img/{{ filename }}">{{ filename }}</a></li>
{% endfor %}
```
becomes:
```
{% for filename in images %}
  <li><a href="img/{{ filename | url_encode }}">{{ filename }}</a></li>
{% endfor %}
```
Ah, much better. Works perfectly.

Wrapping up

I hope you see the benefit of using templating engines and a static site generator for your web sites. In upcoming tutorials, we’ll go over the benefits of using a static site generator with multiple templates. Specifically, how to use layouts (a wrapper to separate your HTML boilerplate from your actual content) and external data files (pair nicely with front matter to easily manage your data across multiple templates).

Eleventy Tutorials

Level 1—Data driven templates (You are here)
Level 2—Adding filters

Zach Leatherman is a builder for the web at Font Awesome and the creator/maintainer of Eleventy (11ty), an award-winning open source site generator. At one point he became entirely too fixated on web fonts. He has given 84 talks in nine different countries at events like Beyond Tellerrand, Smashing Conference, Jamstack Conf, CSSConf, and The White House. Formerly part of CloudCannon, Netlify, Filament Group, NEJS CONF, and NebraskaJS. Learn more about Zach »