Zach’s ugly mug (his face)

Zach Leatherman

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

24 Jan 2018 Zach Leatherman 12 min read
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.

Installation

  1. 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.
  2. 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.

via https://bukk.it/parrot.gif

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:

  1. 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.
  2. 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 threeor more <li> entries individually. Three isn’t bad. But what if our site grows to 300 images?
  3. 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