11ty, A guide.

Static Site Generation? Wha?

To me static websites denote static HTML files, circa 90's internet. We've moved a ways forward since then, with the evolution from Server Side Rendered websites, to Dynamic web apps, and back to Server Side Rendered web apps. And thats not talking about the CMSs of the world. Something common to these approaches, is the underlying need of having a web server to populate information as needed by the application.

The Jamstack pattern attempts to be a hybridisation of these approaches, where you can build layouts and a componentised web application that renders into static HTML files which can be hosted anywhere. 11ty is an implementation that follows the Jamstack principles and is built on top of Node.

Why 11ty?

If you follow the Github Pages guide for hosting on their platform, they direct you to use a Jamstack platform called Jekyll. Jekyll itself is completely functional as a tool, but it does require a functioning Ruby installation. 11ty on the other hand is built upon Node, which has a significantly higher adoption rate across engineers.

Similar to Jekyll, you can host a static site built by 11ty in Github Pages, or any other way you would host a HTML website.

How do I get started?

Before cracking into it, you'll need to have access to a computer which has NodeJS installed onto it. 11ty requires at least Node@14, but you should be able to proceed with a more up to date version of Node.

$ mkdir <11ty-directory>
$ cd <11ty-directory>
$ npm-init -y
$ npm install @11ty/eleventy

The commands above create a directory to store the 11ty application, creates an NPM/Node project in said directory, and installs 11ty to it. This allows us to interface with the 11ty via the npm run-scripts, which we will setup below.

"scripts": {
    "build": "eleventy",
    "serve": "eleventy --serve"
}

Add the following to your package.json file. These commands can be triggered by writing npm run build and npm run serve, and will compile your 11ty site into HTML and serve the 11ty site on http://localhost:8080 respectively.

Harnessing your inner Content Creator!

A website is literally and figuratively nothing without content. We'll start by following the default pattern of using an index.html to start as our root. Copy the following code snippet into your index.html file to render out Hello World!.

<head>
    <title>My WebPage</title>
</head>
<body>
    <p>Hello World!</p>
</body>

If you run npm run serve in your terminal, you should be able to see the HTML being rendered out in your browser by going to localhost:8080.
Having one page is fine, but having two pages really shows off your wealth. Create a second page called secret.html. Inside, add the following HTML code

<head>
    <title>My Secret Page</title>
</head>
<body>
    <p>Shhh! Secrets Ahoy</p>
    <a href="/">Home<a>
</body>

And add the following snippet to your index.html to allow navigation to your new page.

<body>
    <p>Hello World!</p>
    <a href="secret.html">👀</a>
</body>

Voila, we now have a functioning website, with multiple pages to really show off our sophistication.

Template, Template, Template.

We may have a functioning website, but we haven't really done anything to differentiate 11ty from plain old HTML. One of the benefits of 11ty is the ability to use layouts for abstracting away boilerplate code, and applying a stylistic theme across pages. 11ty supports a number of template languages, but we'll focus on using Liquid.

With Liquid, we are firstly going to create a template for our pages. We are going to abstract away the <head> component and place that inside of the template. Create a directory called _includes and create a file called main.liquid inside of there. Add the following code to main.liquid.

---
title: Default title
---
<html>
<head>
<title>{{ title }}</title>
</head>
<body>
    {{ content }}
    <footer>
        <p>YOUR WEBSITE FOOTER</p>
    </footer>
</body>
</html>

We've now created a template which takes and renders some arbitrary content, and adds a footer to each page using the template. Cool. You would have noticed a couple of special non-html functions being used. These are ways of accessing 11ty variables inside of the template. title will be set as Default title unless it's set by the page using the template. Likewise content injects all of the content in the page that is utilising the template.

The following code snippet should be added to index.html. We will use the created layout to remove boilerplate from the <Head> and add the footer to it automatically.

---
title: Main Page
layout: main
---
<body>
    <p>Hello World!</p>
</body>

You should notice that our home page now renders with the the title of Main Page (see the name in the current tab in your browser), and it has a footer inserted now.

Hosting your site

After you've built your website, you should see a directory called _site. Inside of _site you will be able to see the static HTML representing our new website.
Now that we have our HTML, we have the envious task of deciding how to share our site with other. Github Pages provides a free way to host our website.

In order to deploy our website, we need to do the following steps

Create a public repository called <GITHUB_USERNAME>.github.io
Copy all the contents of your _site directory into the root of the repository
Admire your newly minted website on <GITHUB_USERNAME>.github.io