Possibly The Easiest Way to Run an SSG

February 4, 2020

"Static Site Generator," that is. We'll get to that in a second.

Netlify is a sponsor of this site (thank you very much), and I see Zach Leatherman has gone to work over there now. Very cool. Zach is the creator of Eleventy, an SSG for Node. One thing of the many notable things about Eleventy is that you don't even have to install it if you don't want to. Lemme set the stage.

Say you have a three-page website, and one of the reasons you want to reach for an SSG is because you want to repeat the navigation on all three pages. An "HTML include," one of the oldest needs in web development, is in there! We've covered many ways to do it in the past. So we have...

/my_project
- index.html
- about.html
- contact.html

And each of those HTML files needs this repeated chunk of navigation.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Southside Laundromat</title>
  </head>
  <body>
    {{ INCLUDE NAVIGATION HERE }}

    Unique content to this page.

  </body>
</html>

Well why don't we chuck that block of navigation into a file, so...

/my_project
- /_includes
  - nav.html
- index.html
- about.html
- contact.html

Which is something like...

<nav>
  <a href="/">Home</a>
  <a href="/about/">About</a>
  <a href="/contact/">Contact</a>
</nav>

So how do we actually do the include? This is where Eleventy comes in. Eleventy supports a bunch of templating languages, but the default one is Liquid. Liquid supports file includes! Like this...

{% include ./nav.html %}

So that's the line I put in each of the three HTML files. How do I process it then? Isn't this the moment where I have to install Eleventy to get that all going? Nope, I can run a single command on the command line to make this happen (assuming I have npm installed):

npx @11ty/eleventy

Here's a 30-second video showing it work:

There is no package.json. There is no npm install. In a sense, this is a zero-dependency way to processes a static site, which I think is very cool. Eleventy processes it all into a _site folder by default.

Say I want to deploy this static site... over on the Netlify side, I can tell it that what I want deployed is that _site folder. I don't need to commit it either (and you shouldn't), so I can put that in a .gitignore file. Netlify can build it with the same exact command.

I could chuck those settings into a file if that is easier to manage than the site itself. Here's what would go into a netlify.yml file:

build:
  command: "npx @11ty/eleventy"
  publish: _site

The point of this article is Check out how cool this is that you don't even have to install anything to run an SSG! That involves a speed tradeoff. It will be faster, both locally and for cloud computers running your builds, to install packages.

As I was working on this baby demo, I ended up wanting a smidge of configuration for Eleventy in that I wanted my CSS files to come over to the processed site, so...

module.exports = function(eleventyConfig) {
  eleventyConfig.addPassthroughCopy("./styles");
};

That's all.